Add support for Sphinx documentation builder

2 files changed, 136 insertions, 0 deletions

diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index 571d06d..085c147 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -41,6 +41,8 @@ include::asciidoc.asciidoc[Asciidoc documentation]
 
 include::edoc.asciidoc[EDoc comments]
 
+include::sphinx.asciidoc[Sphinx documentation]
+
 [[tests]]
 = Tests
 
diff --git a/doc/src/guide/sphinx.asciidoc b/doc/src/guide/sphinx.asciidoc
new file mode 100644
index 0000000..a20dee5
--- /dev/null
+++ b/doc/src/guide/sphinx.asciidoc
@@ -0,0 +1,134 @@
+[[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'.