Generating HTML docs from docstrings

To build this documentation, we first need to add some extensions in our Sphinx setup.

autodoc pulls documentation from docstrings
napoleon enables Sphinx to parse both NumPy and Google style docstrings

Open conf.py, and modify the extensions list:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
]

and add the option to display documentation both from a class docstring and its __init__ methods’s.

autoclass_content = 'both'

Now, we need to run the command sphinx-apidoc to build rst files out of our docstrings. We need to specify the output path and module path, so from the root of your repo, run:

# from the project root
sphinx-apidoc --output-dir docs src/sphinxy --separate

You can see that Sphinx created an rst file for the package, two rst files for each of the modules riddle and sphinx, as well as a modules.rst file, which acts as a module directory.

You do not need to re-run sphinx-apidoc to generate new .rst if you modify their corresponding .py files! You’d only ever need to re-run sphinx-apidoc if you add more modules to your project.

Next, we are going to edit index.rst to add a reference to modules, so that it appears in the table of contents:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

Now, we’re ready to build our docs again:

# from the docs dir
make html

Preview index.html on your browser. You should be able to see links to each of the modules. Clicking on a module should render its API documentation.

Instead of manually running make html every time you update your docs, you can use the extension sphinx.autobuild. This will automatically rebuild your documentation on file save and auto-reload the HTML pages in the browser. Learn more here.

Finally, commit and push your documentation src files to your remote repository. To ensure you don’t accidentally commit any generated html files, add the _build/ directory to a .gitignore file at the root of your repository, so that these files are ignored by git:

_build/

Now commit and push your documentation src files:

# from the project root
git add docs .gitignore
git commit -m "Add documentation"
git push origin main

🙌 You have now reached the 05-generate-docs part of the tutorial. If not, check out that branch and continue from there.

Previous: Documenting your API Next: Selecting a theme