diff options
Diffstat (limited to 'docs/en/erlang.mk/1/guide/sphinx.asciidoc')
| -rw-r--r-- | docs/en/erlang.mk/1/guide/sphinx.asciidoc | 129 |
1 files changed, 0 insertions, 129 deletions
diff --git a/docs/en/erlang.mk/1/guide/sphinx.asciidoc b/docs/en/erlang.mk/1/guide/sphinx.asciidoc deleted file mode 100644 index d4de20dd..00000000 --- a/docs/en/erlang.mk/1/guide/sphinx.asciidoc +++ /dev/null @@ -1,129 +0,0 @@ -[[sphinx]] -== Sphinx documentation - -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 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 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: - -[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: - ----- -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. - -[source,bash] -$ make docs # all the docs, including EDoc and AsciiDoc if applicable -$ make sphinx # Sphinx docs specifically - -=== Erlang.mk configuration - -Erlang.mk defaults to the following configuration: - -[source,make] -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 -http://www.sphinx-doc.org/en/stable/invocation.html#cmdoption-sphinx-build-b[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. - -=== 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': - -[source,python] ----- -man_pages = [ - ('doc_name', 'page_name', 'Manpage Title', ['Page Author'], 1), -] ----- - -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'. |