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