Sphinx Extensions ================= Sphinx comes with many features, and you don't always need all of them. Therefore, Sphinx lets you configure the things that you want, and turn off the things you don't want. When we did ``sphinx-quickstart`` in the beginning, we were asked several questions. What we did was basically turning on and off some of those. These different features are called Sphinx "extensions". Sphinx has various built-in `extensions `_. There are also various third-party extensions built by the community. I'll share several of my favorite extensions. ------------------- Built-in extensions ------------------- These extensions are built-in and do not require additional package to be installed. Autodoc ------- Automatically include documentation from docstrings by the using the :doc:`Autodoc ` extension. First, your docstrings **must be written in reStructuredText**. #. Enable the extension Open the ``conf.py`` file, and add ``sphinx.ext.autodoc`` to the list of ``extensions``. Example ``conf.py``: .. code:: python extensions = [ ... 'sphinx.ext.autodoc', ... ] #. Insert the path to the module Next, still in ``conf.py``, insert the path to the module that you want to auto-document. The path should be relative to your ``docs`` directory. For example, add the following lines to the top of ``conf.py``: .. code:: python import os import sys sys.path.insert(0, os.path.abspath("../")) #. Create the documentation file Create a new documentation file, where you want the autogenerated docstrings to be rendered. For example, you can create a ``reference_index.rst`` within the ``docs`` directory. #. Specify the modules you want the documentation to be generated In ``reference_index.rst`` file, add the following roles:: .. automodule:: modulename :members: Don't forget to add a section header to the top of the doc! #. Add it to your toctree Go to your ``index.rst`` file, and include ``reference_index`` to the toctree. #. Build the doc Generate the documentation, and view the rendered result. Note that, only modules and members that have docstrings will have documentation autogenerated this way. If you have a function that doesn't have any docstring, then you will not see that function in the autogenerated documentation. **Go write some docstrings!** The following shows an example of writing docstring, along with the format of specifying function parameters: .. code:: python def stock_up(inhabitant, quantity): """Add more fish or shrimp to the tank. :param inhabitant: The type of inhabitant, either shrimp of fish :param quantity: The number of fish or shrimp to be added :raises TankIsFullError: if the tank is already full """ Intersphinx ----------- You can cross-reference other external Sphinx documentation by using the :doc:`Intersphinx `. Some examples, are when you want to reference the official Python documentation, or other project's documentation. #. Enable the extension Open the ``conf.py`` file, and add ``sphinx.ext.intersphinx`` to the list of ``extensions``. Example ``conf.py``: .. code:: python extensions = [ ... 'sphinx.ext.intersphinx', ... ] #. Specify the intersphinx mapping Still in ``conf.py``, add the ``intersphinx_mapping`` value. You need to provide the name of the project, and the url to the project's Sphinx documentation. For example, if we want to link to the official Python docs, as well as the Sphinx documentation: .. code:: python intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), } Then, within our documentation, we can reference those documentation easily. For example, to reference various parts of Python documentation:: - :mod:`asyncio` - :class:`bool` - :exc:`SyntaxError` - :ref:`network IO and IPC ` To reference `Sphinx`_'s, documentation: we'd need to use the name ``sphinx``:: - :ref:`sphinx:ref-role` - :doc:`sphinx:usage/extensions/intersphinx` - :doc:`Intersphinx ` Try them out to see what is rendered. Linkcheck --------- Sphinx can check for broken external links in your documentation. Run the following command in the command line, from within your ``docs`` directory: .. code:: bash (.env)[../docs]$ sphinx-build -b linkcheck . _build/linkcheck I'd recommend including this check as part of your CI, so you can ensure the integrity of links in your documentation. .. seealso:: `Options for the linkcheck builder `_ documentation. Documentation Coverage ---------------------- This extension can be used to generate a report of which parts of your codebase is missing documentation. #. Enable the extension Open the ``conf.py`` file, and add ``sphinx.ext.coverage`` to the list of ``extensions``. Example ``conf.py``. .. code:: python extensions = [ ... 'sphinx.ext.coverage', ... ] #. Run the coverage builder Run the following command in the command line, from within your ``docs`` directory: .. code:: bash (.env)[../docs]$ sphinx-build -b coverage . _build/coverage #. View the output Once the above command has been run, you should see several files under the ``_build/coverage/`` directory. Those files will tell you which parts of your codebase do not have docstrings. ---------------------- Third-party Extensions ---------------------- You'll need to install additional packages for the following extensions. .. _autobuild-extension: sphinx-autobuild ---------------- Authoring Sphinx documentation can be tedious and cumbersome, when you have to always re-build the documentation by running ``make html`` and then re-load your browser. Install `sphinx-autobuild`_ to makes it easier! `sphinx-autobuild`_ can automatically watch for changes in your docs, and re-build the documentation for you. .. code:: bash (.env)[../docs]$ python3 -m pip install sphinx-autobuild==2021.3.14 (.env)[../docs]$ sphinx-autobuild . ./_build/html You can now open the url http://127.0.0.1:8000/ on your browser. Now, whenever you make changes and save your documentation, it will be automatically re-loaded. sphinx-copybutton ----------------- Often you want to share code examples in your documentation, and you want your readers to be able to easily copy and paste your code samples. You'll notice that within this tutorial, there are a little "Copy" button on each of the code blocks. This is because we're using the `sphinx-copybutton`_ extension. #. Install the extension .. code:: bash (.env)[../docs]$ python3 -m pip install sphinx-copybutton==0.3.1 #. Enable the extension Open the ``conf.py`` file, and add ``sphinx_copybutton`` to the list of ``extensions``. Example ``conf.py``: .. code:: python extensions = [ ... 'sphinx_copybutton', ... ] #. Build and view the documentation Themes ------ You can customize the look of your documentation by choosing a different theme. The default Sphinx theme is `alabaster`_. This tutorial is using the `furo`_ theme. Browse through various themes in the `Sphinx Themes Gallery`_. Follow the links there. Each theme should have an instruction on how to customize it. .. _Sphinx: https://www.sphinx-doc.org/en/master/ .. _sphinx-autobuild: https://github.com/executablebooks/sphinx-autobuild .. _sphinx-copybutton: https://sphinx-copybutton.readthedocs.io/en/latest/ .. _alabaster: https://alabaster.readthedocs.io/en/latest/ .. _Sphinx Themes Gallery: https://sphinx-themes.org/#themes .. _furo: https://pradyunsg.me/furo/