[[sphinx]]
== Sphinx documentation

Erlang.mk includes targets for running
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 form 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 '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:

[literal]
----
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:

[literal]
----
Other Page
==========

Lorem ipsum dolor sit amet...
----

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

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

=== Erlang.mk configuration

Default Erlang.mk settings are equivalent to adding to project's makefile
following lines:

[source,make]
SPHINX_FORMATS = html
SPHINX_SOURCE = doc

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

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 `-C` option,
though you will need to manually call `make sphinx` or add `sphinx` target to
dependencies of `docs`.

`$(SPHINX_FORMATS)` variable lists formats to generate. By default only HTML
is generated, but it can also include man pages or LaTeX document for building
PDF. See
http://www.sphinx-doc.org/en/stable/invocation.html#cmdoption-sphinx-build-b[description of `-b` option]
for `sphinx-build` for 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 specific format, you can set `$(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 `man_pages` option in 'doc/conf.py':

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

As http://www.sphinx-doc.org/en/stable/config.html#options-for-manual-page-output[Sphinx documentation]
says, the structure is following:

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

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

NOTE: You probably want to include a link to the man page in other
documentation, possibly in 'doc/index.rst'.