anchor.diff:  [[sphinx]]
   == Sphinx documentation
   
  -Erlang.mk includes targets for running
  +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 form a set of
  +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 'doc'
  +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.
   
  
positive.code: === 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]
  ----
  
negative.code: ]
  ----
  
  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'.
  