Sphinx sphinx-quickstart sphinx-apidoc auto generate API documents

How to use Sphinx?

Sphinx uses reStructuredText as its markup language. 

The process of Sphinx generating documents is like this:

Project source code (Python or other supported languages)->reStructuredText files ->documents (HTML or other supported format)

Sphinx provides two command-line tools: sphinx-quickstart and sphinx-apidoc.

• sphinx-quickstart sets up a source directory and creates a default configuration, conf.py, and a master document, index.rst, which serves as a welcome page of a document.
  • After running sphinx-quickstart, the layout of the docs folder looks like:

  • docs
    ├── Makefile
    ├── build
    ├── make.bat
    └── source
        ├── _static
        ├── _templates
        ├── conf.py
        └── index.rst

• sphinx-apidoc generates reStructuredText files to document from all found modules.
  • After running sphinx-apidoc -f -o source/ ../trees/ the layout of the docs folder looks like:
    • modules.rst and trees.rst and so on being added to source folder.

  • docs
    ├── Makefile
    ├── build
    │   └── doctrees
    │       ├── environment.pickle
    │       └── index.doctree
    ├── make.bat
    └── source
        ├── _static
        ├── _templates
        ├── conf.py
        ├── index.rst
        ├── modules.rst
        ├── trees.bin.rst
        ├── trees.binary_trees.rst
        └── trees.rst

In short, we use these two tools to generate Sphinx source code, i.e., reStructuredText files,

and we modify these reStructuredText files,

and finally use Sphinx to build excellent documents. 

Workflow

 The same as software needs a developer’s maintenance, writing a software document is not a one-time job.

It needs to be updated when the software changes.

The picture below demonstrates the basic Sphinx workflow.

The following sections detail each step of the workflow.

Prepare 

Before we start using Sphinx, we need to set up our working environment.

• use sourecode  # python -m pip install -r requirements.txt

  • user@ubuntu:~$ python3.9 -m venv sphinxvenv
    user@ubuntu:~$ source sphinxvenv/bin/activate
    (sphinxvenv) user@ubuntu:~$ git clone https://github.com/shunsvineyard/python-sample-code.git
    (sphinxvenv) user@ubuntu:~$ cd python-sample-code/
    (sphinxvenv) user@ubuntu:~/python-sample-code$ python -m pip install -r requirements.txt

•   pip3.9 install Sphinx

Step1: Use sphinx-quickstart to generate Sphinx source directory with conf.py and index.rst

Assume we want to put all the document related files in the docs directory.

So, we begin by creating a Sphinx documentation directory, docs.

Then, we go to the docs directory and run sphinx-quickstart.

someone@some-pc Lib % mkdir docs
someone@some-pc Lib % cd docs
someone@some-pc docs % sphinx-quickstart 

Once we run sphinx-quickstart, it asks a few questions about this project. The followings are the example answers for these questions.

Welcome to the Sphinx 7.3.7 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: Instrument
> Author name(s): Zoro.Zhang
> Project release []: V2.1.1 Alpha

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: 

Creating file /Users/zoro.zhang/code/auto_tools/Lib/docs/source/conf.py.
Creating file /Users/zoro.zhang/code/auto_tools/Lib/docs/source/index.rst.
Creating file /Users/zoro.zhang/code/auto_tools/Lib/docs/Makefile.
Creating file /Users/zoro.zhang/code/auto_tools/Lib/docs/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /Users/zoro.zhang/code/auto_tools/Lib/docs/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

At the end of the sphinx-quickstart, it shows how to build the documents.

You should now populate your master file /Users/zoro.zhang/code/auto_tools/Lib/docs/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Note: Sphinx is not a tool that offers fully automatic documents generation like Doxygen. sphinx-quickstart only generates some default files such as index.rst and conf.py with basic information answered by a user. Therefore, we need to do some work to make the documents real. 

Step2: Configure the conf.py

sphinx-quickstart generates a few files, and the most important one is conf.py, which is the configuration of the documents.

Although conf.py serves as a configuration file, it is a real Python file.

The content of conf.py is Python syntax. 

Using Sphinx to generate a document is highly configurable.

This section demonstrates the most basic configurations:

1. the path to the project source code,
2. the theme for the documents,
3. and extensions.

Step2.1: Set the path to the project

Add this to conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # . is the path of this file

Step2.2: Select the Theme

Sphinx provides many built-in themes. The default is alabaster.

html_theme = 'alabaster'

In this tutorial, we change it to bizstyle.

html_theme = 'bizstyle'

More themes and their configurations can be found at HTML Theming — Sphinx documentation

Step2.3: Add autodoc extensions.

Since "automodule" is one directive type of "autodoc".

And we used it in the following xxx.rst.

extensions = [
    'sphinx.ext.autodoc'
]

 The whole conf.py is as below after Step2.1-Step2.3

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # . is the path of this file

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Instrument'
copyright = '2024, Zoro.Zhang'
author = 'Zoro.Zhang'
release = 'V2.1.1 Alpha'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx.ext.autodoc'
]

templates_path = ['_templates']
exclude_patterns = []



# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'bizstyle'
html_static_path = ['_static']

Step3: Use sphinx-apidoc to generate reStructuredText files from source code

sphinx-apidoc is a tool for automatically generating reStructuredText files from source code, e.g. Python modules. To use it, run

$ sphinx-apidoc -f -o <path-to-output> <path-to-module>

-f means force overwriting of any existing generated files.

-o means the path to place the output files.

For the Demo Project, we run the following command.

someone@some-pc docs % sphinx-apidoc -f -o source/ ../InstrumentAgent

Complete usage of sphinx-apidoc is at sphinx-apidoc — Sphinx documentation.

Step4: Edit index.rst and the generated reStructuredText files

The other important file that sphinx-quickstart generates is index.rst. 

index.rst is the master document that serves as a welcome page and contains the root of the ‘’table of contents tree’’ (toctree).

The toctree initially is empty when sphinx-quickstart creates index.rst.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Step4.1: Add the modules to the index.rst

The generated modules.rst contains all the modules.

So we need to add the modules.rst to index.rst.

To add document to be listing on the welcome page (index.rst), do

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

Note: when to add another reStructuredText file, use the file name without extension(modules instead of modules.rst).

If there is a hierarchy of the file(or if modules.rst and index.rst not in same path), use forward slash ‘’/’’ as directory separators. 

Reminder there is a empty line between :caption and moudles.

The whole index.rst as below

index.rst

.. Instrument documentation master file, created by
   sphinx-quickstart on Fri Jun 28 10:49:50 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Instrument's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Step 5: Build the documents

The last step to generate the documents is to issue make html (if we want to generate HTML-based documents). You can make clean if you rebuild.

someone@some-pc docs % make html
Running Sphinx v7.3.7
making output directory... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 3 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] InstrumentAgent
...
...
...
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] modules
generating indices... genindex py-modindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, n warnings.

The HTML pages are in build/html.

After we run the make html command, a build folder is created under docs. Also, the HTML-based documents are located at build/html.

The whole folder looks like this:

The generated document looks like this:

 参考文献：Using Sphinx for Python Documentation - Ilha Formosa 1544