Sphinx setup summary

Overview

Sphinx is convenient for creating documentation for Python packages. If you use sphinx-apidoc, autodoc, API reference will be created automatically from docstrings. When using these, the same setup is always required, so I will summarize them as a memorandum.

Preparation

Install sphinx and create a directory for documents.

$ pip install sphinx
$ mkdir docs
$ cd docs

As a result, assume that the directory structure is as follows.

.
├── README.md
├── docs
├── <your package>
└── tests
 └── Tests

sphinx-quickstart Basically, by default, only the following items are set.

--separate source and build --autodoc: automatically insert docstrings from modules is yes --mathjax yes if needed --viewcode is also yes if needed

sphinx-apidoc settings

Edit the Makefile to call sphinx-apidoc when compiling the document.

First, create a target for sphinx-apidoc. The file automatically generated by sphinx-apidoc is saved in source / modules for import with wildcards.

Makefile

.PHONY: sphinx-apidoc
sphinx-apidoc:
    sphinx-apidoc -f -o source/modules -M "../<module_path>/"
    #Deleted because it is an obstacle when importing with glob
    rm source/modules/modules.rst

Then add the sphinx-apidoc target to the dependencies of all targets. For example, for an html target

Makefile

.PHONY: html
# html:
html: sphinx-apidoc #Add this
    $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
    @echo
    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Editing the source file

Add the following to source / conf.py so that the target package is included in the sphinx path.

conf.py

import sys
import os
sys.path.insert(0, os.path.abspath("../.."))

Then, in order to read the file generated by sphinx-apidoc, add the following to source / index.rst.

index.rst

.. toctree::
   :glob:
   :maxdepth: 2

   modules/*

Finally, change the design to your liking. I personally like the Read the docs theme, so add the following to source / conf.py.

conf.py

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

compile

Compile in the docs directory

$ make html