Example project

Simple example that hopefully demonstrates how to use sphinx in autodoc.

Map of important files:

• docs/ -- Where all docs-related content is kept. It doesn't have to be in its own folder, but it's a common convention.

  • conf.py -- The configuration file for sphinx. See this file for more details on how to configure Sphinx for use with autodoc.

  • index.rst -- Root document that will become index.html in the generated docs. It's conventional to put a toctree or at least some links to other pages in the docs here.

  • module.rst -- Where the autodoc for the example module is invoked.

• src/ -- Where all the Python sources are kept. Also not a requirement to have them separate, but a convention.

  • module/ -- The example module (in this case, a folder-type module with an __init__.py specifying the exported names).

    • __init__.py -- Entry point for the module specifying the exported symbols. Sphinx autodoc uses this to figure out what parts of the module to add to the docs.

    • module_class.py -- Defines the Example class used to showcase the autodoc features.

• simple.py -- A simple file-style module with a couple more exported names.

Running Sphinx

First, make sure Sphinx is installed.

python3 -m pip install -r requirements.txt

Then, you can generate the docs:

sphinx-build -b html docs/ docs-out

And view them in your browser:

xdg-open docs-out/index.html