[[sphinx]]
== Sphinx documentation

Erlang.mk includes targets for running the
http://www.sphinx-doc.org/[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
http://www.sphinx-doc.org/en/stable/rest.html[reST] documents. There is
a http://www.sphinx-doc.org/en/stable/tutorial.html[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:

[source,python]
----
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.

[source,bash]
$ 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:

[source,make]
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
http://www.sphinx-doc.org/en/stable/invocation.html#cmdoption-sphinx-build-b[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':

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

As the
http://www.sphinx-doc.org/en/stable/config.html#options-for-manual-page-output[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'.