A minimal example project using Sphinx autodoc with some Python code.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
khr e9fc2d8e02 Add constant example 10 months ago
docs Add constant example 10 months ago
src Add constant example 10 months ago
.gitignore Example sphinx project using autodoc 10 months ago
README.md Example sphinx project using autodoc 10 months ago


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