Cowboy 2.3.0

1 files changed, 129 insertions, 0 deletions

diff --git a/docs/en/erlang.mk/1/guide/sphinx.asciidoc b/docs/en/erlang.mk/1/guide/sphinx.asciidoc
new file mode 100644
index 00000000..d4de20dd
--- /dev/null
+++ b/docs/en/erlang.mk/1/guide/sphinx.asciidoc
@@ -0,0 +1,129 @@
+[[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'.