Auto-generating the project API documentation

Sphinx comes with another handy tool (sphinx-apidoc) which can be used to automatically generate the API documentation for all source or src modules of the project (assuming you have already been following some best practices when it comes to documenting your code).

The following steps demonstrate how to make use of this handy feature.

1. Open the conf.py file in an editor. At the top of the file, assign a system path for locating the project modules directory by including the following line of code:

   sys.path.insert(0, os.path.abspath(<relative_path_to_source_modules>))
   

   

2. Run sphinx automatic API documentation to automatically generate an .rst file for each module located in the src folder. This also generates a modules.rst file containing a list of all the src modules. -f forces override of any previously written .rst files with the same name.

   sphinx-apidoc -f -o source <relative_path_to_source_modules>
   

   

3. Open the modules.rst file and change the title to ‘API documentation’ or another title, as desired:

   

   Then save the file.

4. Add a cross-reference to the modules.rst file in the toctree in the index.rst file:

   .. toctree::
      :maxdepth: 5
      :caption: My contents are better than your contents:
   
      mynewsection
      modules
   

5. Update the html pages with any changes (make html):

   

   

Edit the text within each .rst module by adding directives to alter their output/behaviour. Some examples here.