Erlang.mk User Guide

+ +

Prev		Next

Chapter 16. Sphinx documentation

Erlang.mk includes targets for running the +Sphinx documentation generator, which can produce +documentation in various formats, like HTML, man pages, Texinfo, LaTeX, and +others.

16.1. Writing Sphinx documentation

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.

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

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

16.3. Erlang.mk configuration

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.

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

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

As the +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.

Prev	Up	Next
	Home