Nine Nines: Sphinx documentation

Sphinx documentation

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

Writing Sphinx documentation

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

Basic setup

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

A minimal doc/conf.py will look similar to this:

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
+==========
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   other_page
+
+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

Erlang.mk configuration

Erlang.mk defaults to the following configuration:

SPHINX_FORMATS = html
+SPHINX_SOURCE = doc

To change the location of Sphinx sources, you need to set the $(SPHINX_SOURCE) +variable. The conf.py 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/conf.py 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.

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/conf.py:

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 Erlang.mk’s defaults), doc/doc_name.rst will +be used to generate man/page_name.1.

99s

Sphinx documentation

Writing Sphinx documentation

Basic setup

Erlang.mk configuration

Generating man pages

+ Erlang.mk + 1 + + User Guide +

Navigation

Version select