A minimal example project using Sphinx autodoc with some Python code.
Go to file
khr e9fc2d8e02 Add constant example 2020-07-20 22:10:33 -07:00
docs Add constant example 2020-07-20 22:10:33 -07:00
src Add constant example 2020-07-20 22:10:33 -07:00
.gitignore Example sphinx project using autodoc 2020-07-20 22:04:19 -07:00
README.md Example sphinx project using autodoc 2020-07-20 22:04:19 -07:00

README.md

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