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 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:
```
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:
```
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:

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 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:
```
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:
```
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 <asyncio-streams>`
```
To reference Sphinx’s, documentation: we’d need to use the name sphinx:
```
- :ref:`sphinx:ref-role`

- :doc:`sphinx:usage/extensions/intersphinx`

- :doc:`Intersphinx <sphinx:usage/extensions/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:

(.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.

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.
```
extensions = [
    ...
    'sphinx.ext.coverage',
    ...
    ]
```
Run the coverage builder

Run the following command in the command line, from within your docs directory:
```
(.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.

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.

(.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

(.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:
```
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.