<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>First Steps with Sphinx — Sphinx 1.1.3 documentation</title>
<link rel="stylesheet" href="_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.1.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Sphinx 1.1.3 documentation"
href="_static/opensearch.xml"/>
<link rel="top" title="Sphinx 1.1.3 documentation" href="index.html" />
<link rel="next" title="Invocation of sphinx-build" href="invocation.html" />
<link rel="prev" title="Introduction" href="intro.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<img src="_static/sphinx.png" alt="Sphinx logo" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="invocation.html" title="Invocation of sphinx-build"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="intro.html" title="Introduction"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Sphinx home</a> | </li>
<li><a href="contents.html">Documentation</a>
»</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">First Steps with Sphinx</a><ul>
<li><a class="reference internal" href="#setting-up-the-documentation-sources">Setting up the documentation sources</a></li>
<li><a class="reference internal" href="#defining-document-structure">Defining document structure</a></li>
<li><a class="reference internal" href="#adding-content">Adding content</a></li>
<li><a class="reference internal" href="#running-the-build">Running the build</a></li>
<li><a class="reference internal" href="#documenting-objects">Documenting objects</a></li>
<li><a class="reference internal" href="#basic-configuration">Basic configuration</a></li>
<li><a class="reference internal" href="#autodoc">Autodoc</a></li>
<li><a class="reference internal" href="#more-topics-to-be-covered">More topics to be covered</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="intro.html"
title="previous chapter">Introduction</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="invocation.html"
title="next chapter">Invocation of sphinx-build</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/tutorial.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="first-steps-with-sphinx">
<h1>First Steps with Sphinx<a class="headerlink" href="#first-steps-with-sphinx" title="Permalink to this headline">¶</a></h1>
<p>This document is meant to give a tutorial-like overview of all common tasks
while using Sphinx.</p>
<p>The green arrows designate “more info” links leading to advanced sections about
the described task.</p>
<div class="section" id="setting-up-the-documentation-sources">
<h2>Setting up the documentation sources<a class="headerlink" href="#setting-up-the-documentation-sources" title="Permalink to this headline">¶</a></h2>
<p>The root directory of a documentation collection is called the <a class="reference internal" href="glossary.html#term-source-directory"><em class="xref std std-term">source
directory</em></a>. This directory also contains the Sphinx configuration file
<tt class="file docutils literal"><span class="pre">conf.py</span></tt>, where you can configure all aspects of how Sphinx reads your
sources and builds your documentation. <a class="footnote-reference" href="#id2" id="id1">[1]</a></p>
<p>Sphinx comes with a script called <strong class="program">sphinx-quickstart</strong> that sets up a
source directory and creates a default <tt class="file docutils literal"><span class="pre">conf.py</span></tt> with the most useful
configuration values from a few questions it asks you. Just run</p>
<div class="highlight-rst"><pre>$ sphinx-quickstart</pre>
</div>
<p>and answer its questions. (Be sure to say yes to the “autodoc” extension.)</p>
<p>There is also an automatic “API documentation” generator called
<strong class="program">sphinx-apidoc</strong>; see <a class="reference internal" href="invocation.html#invocation-apidoc"><em>Invocation of sphinx-apidoc</em></a> for details.</p>
</div>
<div class="section" id="defining-document-structure">
<h2>Defining document structure<a class="headerlink" href="#defining-document-structure" title="Permalink to this headline">¶</a></h2>
<p>Let’s assume you’ve run <strong class="program">sphinx-quickstart</strong>. It created a source
directory with <tt class="file docutils literal"><span class="pre">conf.py</span></tt> and a master document, <tt class="file docutils literal"><span class="pre">index.rst</span></tt> (if you
accepted the defaults). The main function of the <a class="reference internal" href="glossary.html#term-master-document"><em class="xref std std-term">master document</em></a> is to
serve as a welcome page, and to contain the root of the “table of contents tree”
(or <em>toctree</em>). This is one of the main things that Sphinx adds to
reStructuredText, a way to connect multiple files to a single hierarchy of
documents.</p>
<div class="sidebar">
<p class="first sidebar-title">reStructuredText directives</p>
<p><tt class="docutils literal"><span class="pre">toctree</span></tt> is a reStructuredText <em class="dfn">directive</em>, a very versatile piece of
markup. Directives can have arguments, options and content.</p>
<p><em>Arguments</em> are given directly after the double colon following the
directive’s name. Each directive decides whether it can have arguments, and
how many.</p>
<p><em>Options</em> are given after the arguments, in form of a “field list”. The
<tt class="docutils literal"><span class="pre">maxdepth</span></tt> is such an option for the <tt class="docutils literal"><span class="pre">toctree</span></tt> directive.</p>
<p><em>Content</em> follows the options or arguments after a blank line. Each
directive decides whether to allow content, and what to do with it.</p>
<p class="last">A common gotcha with directives is that <strong>the first line of the content must
be indented to the same level as the options are</strong>.</p>
</div>
<p>The toctree directive initially is empty, and looks like this:</p>
<div class="highlight-rst"><pre>.. toctree::
:maxdepth: 2</pre>
</div>
<p>You add documents listing them in the <em>content</em> of the directive:</p>
<div class="highlight-rst"><pre>.. toctree::
:maxdepth: 2
intro
tutorial
...</pre>
</div>
<p>This is exactly how the toctree for this documentation looks. The documents to
include are given as <a class="reference internal" href="glossary.html#term-document-name"><em class="xref std std-term">document name</em></a>s, which in short means that you
leave off the file name extension and use slashes as directory separators.</p>
<p><img alt="more info" class="align-middle" src="_images/more.png" /> Read more about <a class="reference internal" href="markup/toctree.html#toctree-directive"><em>the toctree directive</em></a>.</p>
<p>You can now create the files you listed in the toctree and add content, and
their section titles will be inserted (up to the “maxdepth” level) at the place
where the toctree directive is placed. Also, Sphinx now knows about the order
and hierarchy of your documents. (They may contain <tt class="docutils literal"><span class="pre">toctree</span></tt> directives
themselves, which means you can create deeply nested hierarchies if necessary.)</p>
</div>
<div class="section" id="adding-content">
<h2>Adding content<a class="headerlink" href="#adding-content" title="Permalink to this headline">¶</a></h2>
<p>In Sphinx source files, you can use most features of standard reStructuredText.
There are also several features added by Sphinx. For example, you can add
cross-file references in a portable way (which works for all output types) using
the <a class="reference internal" href="markup/inline.html#role-ref" title="ref role"><tt class="xref rst rst-role docutils literal"><span class="pre">ref</span></tt></a> role.</p>
<p>For an example, if you are viewing the HTML version you can look at the source
for this document – use the “Show Source” link in the sidebar.</p>
<p><img alt="more info" class="align-middle" src="_images/more.png" /> See <a class="reference internal" href="rest.html#rst-primer"><em>reStructuredText Primer</em></a> for a more in-depth introduction to
reStructuredText and <a class="reference internal" href="markup/index.html#sphinxmarkup"><em>Sphinx Markup Constructs</em></a> for a full list of markup added by
Sphinx.</p>
</div>
<div class="section" id="running-the-build">
<h2>Running the build<a class="headerlink" href="#running-the-build" title="Permalink to this headline">¶</a></h2>
<p>Now that you have added some files and content, let’s make a first build of the
docs. A build is started with the <strong class="program">sphinx-build</strong> program, called like
this:</p>
<div class="highlight-rst"><pre>$ sphinx-build -b html sourcedir builddir</pre>
</div>
<p>where <em>sourcedir</em> is the <a class="reference internal" href="glossary.html#term-source-directory"><em class="xref std std-term">source directory</em></a>, and <em>builddir</em> is the
directory in which you want to place the built documentation. The <em class="xref std std-option">-b</em>
option selects a builder; in this example Sphinx will build HTML files.</p>
<p><img alt="more info" class="align-middle" src="_images/more.png" /> See <a class="reference internal" href="invocation.html#invocation"><em>Invocation of sphinx-build</em></a> for all options that <strong class="program">sphinx-build</strong>
supports.</p>
<p>However, <strong class="program">sphinx-quickstart</strong> script creates a <tt class="file docutils literal"><span class="pre">Makefile</span></tt> and a
<tt class="file docutils literal"><span class="pre">make.bat</span></tt> which make life even easier for you: with them you only need
to run</p>
<div class="highlight-rst"><pre>$ make html</pre>
</div>
<p>to build HTML docs in the build directory you chose. Execute <tt class="docutils literal"><span class="pre">make</span></tt> without
an argument to see which targets are available.</p>
<div class="admonition-how-do-i-generate-pdf-documents admonition">
<p class="first admonition-title">How do I generate PDF documents?</p>
<p class="last"><tt class="docutils literal"><span class="pre">make</span> <span class="pre">latexpdf</span></tt> runs the <a class="reference internal" href="builders.html#sphinx.builders.latex.LaTeXBuilder" title="sphinx.builders.latex.LaTeXBuilder"><tt class="xref py py-mod docutils literal"><span class="pre">LaTeX</span> <span class="pre">builder</span></tt></a> and readily invokes the pdfTeX
toolchain for you.</p>
</div>
</div>
<div class="section" id="documenting-objects">
<h2>Documenting objects<a class="headerlink" href="#documenting-objects" title="Permalink to this headline">¶</a></h2>
<p>One of Sphinx’ main objectives is easy documentation of <em class="dfn">objects</em> (in a
very general sense) in any <em class="dfn">domain</em>. A domain is a collection of object
types that belong together, complete with markup to create and reference
descriptions of these objects.</p>
<p>The most prominent domain is the Python domain. To e.g. document the Python
built-in function <tt class="docutils literal"><span class="pre">enumerate()</span></tt>, you would add this to one of your source
files:</p>
<div class="highlight-rst"><pre>.. py:function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)</pre>
</div>
<p>This is rendered like this:</p>
<dl class="function">
<dt id="enumerate">
<tt class="descname">enumerate</tt><big>(</big><em>sequence</em><span class="optional">[</span>, <em>start=0</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#enumerate" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an iterator that yields tuples of an index and an item of the
<em>sequence</em>. (And so on.)</p>
</dd></dl>
<p>The argument of the directive is the <em class="dfn">signature</em> of the object you
describe, the content is the documentation for it. Multiple signatures can be
given, each in its own line.</p>
<p>The Python domain also happens to be the default domain, so you don’t need to
prefix the markup with the domain name:</p>
<div class="highlight-rst"><pre>.. function:: enumerate(sequence[, start=0])
...</pre>
</div>
<p>does the same job if you keep the default setting for the default domain.</p>
<p>There are several more directives for documenting other types of Python objects,
for example <a class="reference internal" href="domains.html#directive-py:class" title="py:class directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:class</span></tt></a> or <a class="reference internal" href="domains.html#directive-py:method" title="py:method directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:method</span></tt></a>. There is also a
cross-referencing <em class="dfn">role</em> for each of these object types. This markup will
create a link to the documentation of <tt class="docutils literal"><span class="pre">enumerate()</span></tt>:</p>
<div class="highlight-rst"><pre>The :py:func:`enumerate` function can be used for ...</pre>
</div>
<p>And here is the proof: A link to <a class="reference internal" href="#enumerate" title="enumerate"><tt class="xref py py-func docutils literal"><span class="pre">enumerate()</span></tt></a>.</p>
<p>Again, the <tt class="docutils literal"><span class="pre">py:</span></tt> can be left out if the Python domain is the default one. It
doesn’t matter which file contains the actual documentation for <tt class="docutils literal"><span class="pre">enumerate()</span></tt>;
Sphinx will find it and create a link to it.</p>
<p>Each domain will have special rules for how the signatures can look like, and
make the formatted output look pretty, or add specific features like links to
parameter types, e.g. in the C/C++ domains.</p>
<p><img alt="more info" class="align-middle" src="_images/more.png" /> See <a class="reference internal" href="domains.html#domains"><em>Sphinx Domains</em></a> for all the available domains and their
directives/roles.</p>
</div>
<div class="section" id="basic-configuration">
<h2>Basic configuration<a class="headerlink" href="#basic-configuration" title="Permalink to this headline">¶</a></h2>
<p>Earlier we mentioned that the <tt class="file docutils literal"><span class="pre">conf.py</span></tt> file controls how Sphinx processes
your documents. In that file, which is executed as a Python source file, you
assign configuration values. For advanced users: since it is executed by
Sphinx, you can do non-trivial tasks in it, like extending <tt class="xref py py-data docutils literal"><span class="pre">sys.path</span></tt> or
importing a module to find out the version your are documenting.</p>
<p>The config values that you probably want to change are already put into the
<tt class="file docutils literal"><span class="pre">conf.py</span></tt> by <strong class="program">sphinx-quickstart</strong> and initially commented out
(with standard Python syntax: a <tt class="docutils literal"><span class="pre">#</span></tt> comments the rest of the line). To change
the default value, remove the hash sign and modify the value. To customize a
config value that is not automatically added by <strong class="program">sphinx-quickstart</strong>,
just add an additional assignment.</p>
<p>Keep in mind that the file uses Python syntax for strings, numbers, lists and so
on. The file is saved in UTF-8 by default, as indicated by the encoding
declaration in the first line. If you use non-ASCII characters in any string
value, you need to use Python Unicode strings (like <tt class="docutils literal"><span class="pre">project</span> <span class="pre">=</span> <span class="pre">u'Exposé'</span></tt>).</p>
<p><img alt="more info" class="align-middle" src="_images/more.png" /> See <a class="reference internal" href="config.html#build-config"><em>The build configuration file</em></a> for documentation of all available config values.</p>
</div>
<div class="section" id="autodoc">
<h2>Autodoc<a class="headerlink" href="#autodoc" title="Permalink to this headline">¶</a></h2>
<p>When documenting Python code, it is common to put a lot of documentation in the
source files, in documentation strings. Sphinx supports the inclusion of
docstrings from your modules with an <em class="dfn">extension</em> (an extension is a Python
module that provides additional features for Sphinx projects) called “autodoc”.</p>
<p>In order to use autodoc, you need to activate it in <tt class="file docutils literal"><span class="pre">conf.py</span></tt> by putting
the string <tt class="docutils literal"><span class="pre">'sphinx.ext.autodoc'</span></tt> into the list assigned to the
<a class="reference internal" href="config.html#confval-extensions"><tt class="xref std std-confval docutils literal"><span class="pre">extensions</span></tt></a> config value. Then, you have a few additional directives
at your disposal.</p>
<p>For example, to document the function <tt class="docutils literal"><span class="pre">io.open()</span></tt>, reading its
signature and docstring from the source file, you’d write this:</p>
<div class="highlight-rst"><pre>.. autofunction:: io.open</pre>
</div>
<p>You can also document whole classes or even modules automatically, using member
options for the auto directives, like</p>
<div class="highlight-rst"><pre>.. automodule:: io
:members:</pre>
</div>
<p>autodoc needs to import your modules in order to extract the docstrings.
Therefore, you must add the appropriate path to <tt class="xref py py-data docutils literal"><span class="pre">sys.path</span></tt> in your
<tt class="file docutils literal"><span class="pre">conf.py</span></tt>.</p>
<p><img alt="more info" class="align-middle" src="_images/more.png" /> See <a class="reference internal" href="ext/autodoc.html#module-sphinx.ext.autodoc" title="sphinx.ext.autodoc: Include documentation from docstrings."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.autodoc</span></tt></a> for the complete description of the
features of autodoc.</p>
</div>
<div class="section" id="more-topics-to-be-covered">
<h2>More topics to be covered<a class="headerlink" href="#more-topics-to-be-covered" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>Other extensions (math, intersphinx, viewcode, doctest)</li>
<li>Static files</li>
<li>Selecting a theme</li>
<li>Templating</li>
<li>Using extensions</li>
<li>Writing extensions</li>
</ul>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>This is the usual lay-out. However, <tt class="file docutils literal"><span class="pre">conf.py</span></tt> can also live in
another directory, the <a class="reference internal" href="glossary.html#term-configuration-directory"><em class="xref std std-term">configuration directory</em></a>. See
<a class="reference internal" href="invocation.html#invocation"><em>Invocation of sphinx-build</em></a>.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="invocation.html" title="Invocation of sphinx-build"
>next</a> |</li>
<li class="right" >
<a href="intro.html" title="Introduction"
>previous</a> |</li>
<li><a href="index.html">Sphinx home</a> | </li>
<li><a href="contents.html">Documentation</a>
»</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
distrib
>
Mageia
>
4
>
i586
>
media
>
core-release
>
by-pkgid
>
c95717a2237548a7bdaddf39c85b0f0f
>
files
>
141
