|
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
<title>Nine Nines: Sphinx documentation</title>
<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'>
<link href="/css/99s.css?r=4" rel="stylesheet">
<link rel="shortcut icon" href="/img/ico/favicon.ico">
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png">
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png">
<link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png">
</head>
<body class="">
<header id="page-head">
<div id="topbar" class="container">
<div class="row">
<div class="span2">
<h1 id="logo"><a href="/" title="99s">99s</a></h1>
</div>
<div class="span10">
<div id="side-header">
<nav>
<ul>
<li><a title="Hear my thoughts" href="/articles">Articles</a></li>
<li><a title="Watch my talks" href="/talks">Talks</a></li>
<li class="active"><a title="Read the docs" href="/docs">Documentation</a></li>
<li><a title="Request my services" href="/services">Consulting & Training</a></li>
</ul>
</nav>
<ul id="social">
<li>
<a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a>
</li>
<li>
<a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a>
</li>
</ul>
</div>
</div>
</div>
</div>
</header>
<div id="contents" class="two_col">
<div class="container">
<div class="row">
<div id="docs" class="span9 maincol">
<h1 class="lined-header"><span>Sphinx documentation</span></h1>
<p>Erlang.mk includes targets for running the <a href="http://www.sphinx-doc.org/">Sphinx documentation generator</a>, which can produce documentation in various formats, like HTML, man pages, Texinfo, LaTeX, and others.</p>
<h2 id="_writing_sphinx_documentation">Writing Sphinx documentation</h2>
<p>Sphinx generates documentation from a set of <a href="http://www.sphinx-doc.org/en/stable/rest.html">reST</a> documents. There is a <a href="http://www.sphinx-doc.org/en/stable/tutorial.html">quick start guide</a> on Sphinx' website. For Erlang.mk, we'll set up a minimal environment instead.</p>
<h2 id="_basic_setup">Basic setup</h2>
<p>By default, Erlang.mk expects Sphinx documentation to be placed in the <em>doc</em> directory, with <em>doc/conf.py</em> config file in particular. The file contains information about the project, among the other things.</p>
<p>A minimal <em>doc/conf.py</em> will look similar to this:</p>
<div class="listingblock"><div class="content">source-highlight: could not find a language definition for python
</div></div>
<p>It points to a <em>doc/index.rst</em> document. A simple skeleton includes a table of contents for all documentation, and links to generated index of terms and a search page:</p>
<div class="listingblock"><div class="content"><pre>My Project
==========
Contents:
.. toctree::
:maxdepth: 2
other_page
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`</pre></div></div>
<p>The skeleton above has a link to one other page, <em>doc/other_page.rst</em>. Simple header with some text will do for now:</p>
<div class="listingblock"><div class="content"><pre>Other Page
==========
Lorem ipsum dolor sit amet...</pre></div></div>
<p>The files above are enough to build HTML documentation to the <em>html</em> directory.</p>
<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>$ make docs <i><font color="#9A1900"># all the docs, including EDoc and AsciiDoc if applicable</font></i>
$ make sphinx <i><font color="#9A1900"># Sphinx docs specifically</font></i></tt></pre>
</div></div>
<h2 id="_erlang_mk_configuration">Erlang.mk configuration</h2>
<p>Erlang.mk defaults to the following configuration:</p>
<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><font color="#009900">SPHINX_FORMATS =</font> html
<font color="#009900">SPHINX_SOURCE =</font> doc</tt></pre>
</div></div>
<p>To change the location of Sphinx sources, you need to set the <code>$(SPHINX_SOURCE)</code> variable. The <em>conf.py</em> file should also be placed in that directory, unless you specify <code>$(SPHINX_CONFDIR)</code>.</p>
<p>The variable <code>$(SPHINX_OPTS)</code> allows to provide options to <code>sphinx-build</code>, which is particularly useful for <code>-D name=value</code> options. You can even forego <em>doc/conf.py</em> file, using <code>-D name=value</code> in combination with the <code>-C</code> option, though in this case you will need to manually call <code>make sphinx</code> or add the <code>sphinx</code> target to dependencies of <code>docs</code>.</p>
<p>The <code>$(SPHINX_FORMATS)</code> 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 <a href="http://www.sphinx-doc.org/en/stable/invocation.html#cmdoption-sphinx-build-b">description of the `-b` option</a> for <code>sphinx-build</code> for a list of known formats.</p>
<p>Formats are by default generated to a directory called after the format (<em>html</em> for HTML, <em>man</em> for man pages, and so on). To change this behaviour for a specific format, you can set the <code>$(sphinx_$(format)_output)</code> variable, e.g. <code>$(sphinx_html_output)</code> for <em>html</em> or <code>$(sphinx_man_output)</code> for <em>man</em>. There are also <code>$(sphinx_$(format)_opts)</code> variables for setting <code>sphinx-build</code> options for a single format only.</p>
<h2 id="_generating_man_pages">Generating man pages</h2>
<p>To generate man pages, you need to include <code>man</code> in <code>$(SPHINX_FORMATS)</code> in your Makefile and define the <code>man_pages</code> option in <em>doc/conf.py</em>:</p>
<div class="listingblock"><div class="content">source-highlight: could not find a language definition for python
</div></div>
<p>As the <a href="http://www.sphinx-doc.org/en/stable/config.html#options-for-manual-page-output">Sphinx documentation</a> indicates, the structure is:</p>
<ul><li><code>doc_name</code> is the path to the man page's source (relative <code>$(SPHINX_SOURCE)</code>), without the <em>.rst</em> suffix
</li>
<li><code>page_name</code> 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
</li>
<li><code>Manpage Title</code> is a short, one-line description, which will be included in the generated man page on a position that's used by the <code>apropos</code> command
</li>
<li><code>Page Author</code> (or more of them) will be included in the autogenerated <code>AUTHOR</code> section. Leaving this field empty disables generating the <code>AUTHOR</code> section
</li>
<li><code>1</code> is the man page section number
</li>
</ul>
<p>With the above configuration (and Erlang.mk's defaults), <em>doc/doc_name.rst</em> will be used to generate <em>man/page_name.1</em>.</p>
<nav style="margin:1em 0">
<a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/">
EDoc comments
</a>
<a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/">
Erlang shell
</a>
</nav>
</div>
<div class="span3 sidecol">
<h3>
Erlang.mk
1
User Guide
</h3>
<ul>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/erlang.mk/1/guide">1</a></li>
</ul>
</div>
</div>
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="span6">
<p id="scroll-top"><a href="#">↑ Scroll to top</a></p>
<nav>
<ul>
<li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li>
</ul>
</nav>
</div>
<div class="span6 credits">
<p><img src="/img/footer_logo.png"></p>
<p>Copyright © Loïc Hoguin 2012-2018</p>
</div>
</div>
</div>
</footer>
<script src="/js/custom.js"></script>
</body>
</html>
|
