Developer workflows#
API reference from docstrings#
If you are using Jupyter Book for package documentation,
it can be time-saving to use the sphinx autodoc extension
to automatically generate the API reference documentation.
To do so,
you first need to add the autodoc
extension to _config.yaml
:
sphinx:
extra_extensions:
- 'sphinx.ext.autodoc'
Then,
you can either use the MyST eval_rst directive,
or create a separate .rst file for the API reference page.
This file can be called anything (e.g. api.rst
)
as long as it is referenced in _toc.yml
,
and it should look something like this:
API Reference
=============
.. automodule:: my_project.my_module
:members:
The next time you build your book,
autodoc
will extract all the docstrings from that module
and create a single documentation page for all of them.
If you want more control and the table of contents in the right margin,
you can add headings and functions individually:
API Reference
=============
Func one
--------
.. autofunction:: my_project.my_module.func_one
Func two
--------
.. autofunction:: my_project.my_module.func_two
If your docstrings are written per the NumPy or Google conventions, you can add the napoleon extension to parse and render them correctly. Another useful extension can insert a link to the source code for each function and there is an option to shorten the function names to just the basename:
sphinx:
extra_extensions:
- 'sphinx.ext.autodoc'
- 'sphinx.ext.napoleon'
- 'sphinx.ext.viewcode'
config:
add_module_names: False
If you have a more complex project structure
and want to recursively extract docstrings of all submodules and their functions,
you can use the autosummary extension
with the :recursive:
option (since Sphinx 3.1).
sphinx:
extra_extensions:
- 'sphinx.ext.autodoc'
- 'sphinx.ext.autosummary'
config:
autosummary_generate: True
Your api.rst
file should now look like this:
API documentation
=================
.. autosummary::
:toctree: _autosummary
:recursive:
my_module
To insert clickable links from the summary page to each functions docstring, you are currently required to modify the default templates, and links will not be enabled by default until at least Sphinx 4. Another option to generate clickable links to functions recursively is the autoapi extension, which can be installed via pip and requires less customization than the above.