Sphinx autodoc#


  • You have added docstrings to a *.py file, and you want them included in this documentation.

Solution: Jupyterbook is a frontend to Sphinx. We simply have to tell Sphinx to autodoc our Python file. Happily sphinx autodoc is already installed by default.

(1) Extend the config-file _config.py:

    - sphinx.ext.autodoc
    add-dot-to-path : '.'

(2) Problem left over: How to tell Sphinx the location of the *.py file? (We have to update the sys.path variable. We assume for simplicity that the *.py file resides in the . (DOT) directory.)

Simply put the follwing trivial file add-dot-to-path.py (yes, indeed only one line) to the . (DOT) directory:

def setup(app): ...

This extension does nothing - but as a side effect this “will […] update the sys.path so the local extension can be found.” https://jupyterbook.org/advanced/sphinx.html#local-sphinx-extensions. For an explanation in detail see add-dot-to-path.py.

(3) To ask Sphinx do autodoc a module:

.. automodule:: hello

Result: c.f. ar_autodoc.