From ad88794506a0ccf0671dd9b909890e0a80b346cc Mon Sep 17 00:00:00 2001 From: Stanislaw Klekot Date: Mon, 30 Oct 2017 20:39:07 +0100 Subject: Add support for Sphinx documentation builder --- doc/src/guide/book.asciidoc | 2 + doc/src/guide/sphinx.asciidoc | 134 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 doc/src/guide/sphinx.asciidoc (limited to 'doc') 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'. -- cgit v1.2.3