User guide¶

Check the documentation of Sphinx for details.

The source code for generating the documentation is written in RST files. This page gives the basic syntax for these files.

Here, we assume that we need to create the documentation of a Python package, that we name pkg_example in the example below.

You can check ViSiAnnoT for an example of documentation.

Create Sphinx documentation¶

Source code¶

At the root of the repository of the package, create the directory doc. Go inside this directory and create the following files:

Makefile:

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
        @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
        @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

requirements.txt (optional, for ReadTheDocs):

sphinx==3.x.x
sphinx_rtd_theme==0.x.0
docutils==0.x
autodocsumm==0.x.x
six==1.x.0
jinja2==3.0.0

Replace the packages versions by the actual versions you use. Regarding jinja2, a specific version is required, otherwise ReadTheDocs encounters a bug. This file must be updated with any Python package that is required for your package.

Inside the directory doc, create the sub-directory source. In this sub-directory are stored all the RST files for generating documentation. In particular, create the following files (do not forget to replace pkg_example with the actual name of your package):

The Sphinx configuration file conf.py, which may be modified according to your needs:

# -*- coding: utf-8 -*-

from os.path import abspath, join, dirname
import sys

path = dirname(abspath(__file__))
sys.path.insert(0, abspath('.'))
sys.path.insert(0, abspath(join(path, '..', '..')))

from pkg_example import __version__ as version
from datetime import datetime


# -- Project information -----------------------------------------------------

project = 'pkg_example'
copyright = '2022-%s, some institution' % datetime.today().year
author = 'John Doe'

# The full version, including alpha/beta/rc tags
release = version


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.imgmath',
    'sphinx.ext.viewcode',
    'sphinx.ext.autosummary',
    'autodocsumm',
]

autodoc_member_order = 'groupwise'
autoclass_content = 'init'
numfig = True

# option of autodocsumm, so that summary table is shown after class docstring
# autoclass directive
autodoc_default_options = {'autosummary': True}


# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The master toctree document.
master_doc = 'index'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

The main RST file index.rst, which contains the table of content of the whole documentation, pointing to RST files:

Welcome to pkg_example's documentation!
===============================

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   intro
   # put here the name of the other RST files


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

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

Then, inside the directory doc/source, you can create as many RST files as wanted and include them in index.rst.

Documentation generation¶

Go to the directory doc and run the following command: make html. A sub-directory build is automatically created and contains the HTML documentation.

The command make clean allows to remove the previously generated documentation.

Create API reference automatically¶

Go to the root of the repository containing the package and run the following command (replace pkg_example by the name of the package): python3 -m tools_doc_sphinx.auto_doc_api pkg_example doc/source

It creates the directory doc/source/APIreference, which contains the RST index files for generating the API documentation. It automatically updates the table of contents in the main index.rst file, so that it is included in the generated documentation.

Use groups in class summary¶

This feature is based on this example of autodocsumm.

Let imagine that there is a class that has a lot of methods that may be grouped into several categories. In the class summary, we want to separate the methods according to the groups (see this example).

The groups are defined in the source code of the class with the following decorators:

Start group:

# *********************************************************************** #
# Group: Methods for widget creation
# *********************************************************************** #

End group:

# *********************************************************************** #
# End group
# *********************************************************************** #

The following line must be added in the preambule of conf.py: from tools_doc_sphinx.summary_groups import setup.

At the same location than conf.py, create the file pkg_name.py, which must contain the following line: PACKAGE_NAME = 'pkg_example' (replace pkg_example by the actual name of the package).

And that’s it! Just run make html to generate the documentation.

Create tree view¶

To create a file with the tree view of the package repository, go to the root of the repository and run the following command: python3 -m tools_doc_sphinx.tree_view_source_code ..

The file tree_view.txt is automatically created. The .gitignore file is taken into account so that files that are ignored in the repository are also ignored in the generated tree view.