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.

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:

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
==========

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 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.

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:

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

As the Sphinx documentation indicates, the structure is:

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