Chapter 17. Sphinx documentation includes targets for running the Sphinx documentation generator, which can produce documentation in various formats, like HTML, man pages, Texinfo, LaTeX, and others.

17.1. Writing Sphinx documentation

Sphinx generates documentation from a set of reST documents. There is a quick start guide on Sphinx' website. For, we’ll set up a minimal environment instead.

17.2. Basic setup

By default, expects Sphinx documentation to be placed in the doc directory, with doc/ config file in particular. The file contains information about the project, among the other things.

A minimal doc/ will look similar to this:

project = 'My Project'
version = '0.0'
release = '0.0.1'
master_doc = 'index'
source_suffix = '.rst'

It points to a doc/index.rst document. A simple skeleton includes a table of contents for all documentation, and links to generated index of terms and a search page:

My Project


.. toctree::
   :maxdepth: 2


Indices and tables

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

The skeleton above has a link to one other page, doc/other_page.rst. Simple header with some text will do for now:

Other Page

Lorem ipsum dolor sit amet...

The files above are enough to build HTML documentation to the html directory.

$ make docs     # all the docs, including EDoc and AsciiDoc if applicable
$ make sphinx   # Sphinx docs specifically

17.3. configuration defaults to the following configuration:


To change the location of Sphinx sources, you need to set the $(SPHINX_SOURCE) variable. The file should also be placed in that directory, unless you specify $(SPHINX_CONFDIR).

The variable $(SPHINX_OPTS) allows to provide options to sphinx-build, which is particularly useful for -D name=value options. You can even forego doc/ file, using -D name=value in combination with the -C option, though in this case you will need to manually call make sphinx or add the sphinx target to dependencies of docs.

The $(SPHINX_FORMATS) variable lists formats to generate. By default only HTML is generated, but it can also build man pages or LaTeX documents which can later be converted to PDF. See the description of the -b option for sphinx-build for a list of known formats.

Formats are by default generated to a directory called after the format (html for HTML, man for man pages, and so on). To change this behaviour for a specific format, you can set the $(sphinx_$(format)_output) variable, e.g. $(sphinx_html_output) for html or $(sphinx_man_output) for man. There are also $(sphinx_$(format)_opts) variables for setting sphinx-build options for a single format only.

17.4. Generating man pages

To generate man pages, you need to include man in $(SPHINX_FORMATS) in your Makefile and define the man_pages option in doc/

man_pages = [
    ('doc_name', 'page_name', 'Manpage Title', ['Page Author'], 1),

As the Sphinx documentation indicates, the structure is:

  • doc_name is the path to the man page’s source (relative $(SPHINX_SOURCE)), without the .rst suffix
  • page_name is the name of the resulting man page, which will be used as a base for the output file name and will be included in the generated man page
  • Manpage Title is a short, one-line description, which will be included in the generated man page on a position that’s used by the apropos command
  • Page Author (or more of them) will be included in the autogenerated AUTHOR section. Leaving this field empty disables generating the AUTHOR section
  • 1 is the man page section number

With the above configuration (and’s defaults), doc/doc_name.rst will be used to generate man/page_name.1.