Introduction to the

Sphinx is a tool for generating documentation quickly and is perfect for generating Python documents.

It has the following advantages:

  • Support a variety of output formats, such as HTML, LaTeX, EPUB, etc.

  • Rich Extensions

  • Structured document

  • Automatic indexing

  • Support syntax highlighting

Sphinx uses reStructuredText as its markup language.

The installation

Install with PIP:

pip install sphinx

Set the source file directory

The root directory that contains the.rst file is called the source file directory, which also contains Sphinx’s configuration file, conf.py.

Enter the source file directory and execute the following command to guide the user to configure the entire project:

sphinx-quickstart

Define file structure

After executing the above command, Sphinx will automatically generate the conf.py file and index.rst in the source file directory. Index.rst is called the main document, which is used by Sphinx as the welcome page.

Index. RST contains the directory tree directive toctree, which Sphinx uses to link to other subdocuments.

The initial value of the toctree directive is null:

. toctree:: :maxdepth: 2

Then you can add a link to a subdocument by using the name of the document, omit the file suffix, or use/if it is a multi-level directory.

. toctree:: :maxdepth: 2 intro tutorial chapter/doc1 ...

We can then create and add the files listed above, and sphnix will automatically insert the chapter titles of these documents into the location of the DocTree directive.

Add content

In addition to the Sphinx source file, which is documented in the reStructuredText markup language, Sphinx provides a few additional directives.

For details, please refer to

ReStructuredText Primer and Sphinx Markup Constructs

Generating documentation

Use the following command to generate the document:

$ sphinx-build -b html sourcedir builddir

Sourcedir refers to the source file directory, and the generated document is placed in the directory specified by builddir.

There is actually an easier way to do this. Sphinx-QuickStart generates a make.bat file that runs the script directly:

make html

The above command generates the document directly in the source file directory.

Object document

One of the things that Sphinx was designed to do was make it easier to document objects in any domain, which is a collection of objects that contain corresponding document comments.

The primary fields are Python fields. For example, the annotation documentation for the Python built-in function enumerate() looks like this:

. py:function:: enumerate(sequence[, start=0]) Return an iterator that yields tuples of an index and an item of the *sequence*. (And so on.)

It will be rendered in the following format:

enumerate(sequence[, start=0])

Return an iterator that yields tuples of an index and an item of the sequence. (and so on.) The content is a comment to the document that we wrote. Since Python is the default domain, you don’t need to specify which domain you belong to.

. function:: enumerate(sequence[, start=0]) ...

Sphinx also provides directives for generating documents for other object types. Examples are py:class and py:method

The basic configuration

Sphinx is configured via conf.py, which uses Python syntax and is saved in UTF-8 by default. See The Build Configuration File for details.

Automatically generate document comments

Sphinx supports extracting documentation comment information from Python source code and generating documentation, which we call autodoc.

To use autodoc, you first need to add ‘sphinx.ext.autodoc’ in the Extensions option of your configuration file. Then we can use the autodoc directive.

For example, to generate documentation for the function io.open(), simply add the following statement to the RST file:

. autofunction:: io.open

You can also directly document the entire class:

. automodule:: io :members:

To extract a document comment, AutoDoc needs to import the module in which the comment resides. So you need to set the module’s path in sys.path.

Set the theme

Recommends to use ReadtheDoc to use the theme, beautiful and simple and generous. First install the theme library:

pip install sphinx_rtd_theme

Then configure conf.py:

import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Jane’s address book