<!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>The TOC tree — 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="up" title="Sphinx Markup Constructs" href="index.html" />
<link rel="next" title="Paragraph-level markup" href="para.html" />
<link rel="prev" title="Sphinx Markup Constructs" href="index.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="para.html" title="Paragraph-level markup"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Sphinx Markup Constructs"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="index.html" accesskey="U">Sphinx Markup Constructs</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="#">The TOC tree</a><ul>
<li><a class="reference internal" href="#special-names">Special names</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Sphinx Markup Constructs</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="para.html"
title="next chapter">Paragraph-level markup</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/markup/toctree.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="the-toc-tree">
<span id="toctree-directive"></span><h1>The TOC tree<a class="headerlink" href="#the-toc-tree" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Since reST does not have facilities to interconnect several documents, or split
documents into multiple output files, Sphinx uses a custom directive to add
relations between the single files the documentation is made of, as well as
tables of contents. The <tt class="docutils literal"><span class="pre">toctree</span></tt> directive is the central element.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Simple “inclusion” of one file in another can be done with the
<a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#include">include</a> directive.</p>
</div>
<dl class="directive">
<dt id="directive-toctree">
<tt class="descname">.. toctree::</tt><a class="headerlink" href="#directive-toctree" title="Permalink to this definition">¶</a></dt>
<dd><p>This directive inserts a “TOC tree” at the current location, using the
individual TOCs (including “sub-TOC trees”) of the documents given in the
directive body. Relative document names (not beginning with a slash) are
relative to the document the directive occurs in, absolute names are relative
to the source directory. A numeric <tt class="docutils literal"><span class="pre">maxdepth</span></tt> option may be given to
indicate the depth of the tree; by default, all levels are included. <a class="footnote-reference" href="#id3" id="id1">[1]</a></p>
<p>Consider this example (taken from the Python docs’ library reference index):</p>
<div class="highlight-rst"><pre>.. toctree::
:maxdepth: 2
intro
strings
datatypes
numeric
(many more documents listed here)</pre>
</div>
<p>This accomplishes two things:</p>
<ul class="simple">
<li>Tables of contents from all those documents are inserted, with a maximum
depth of two, that means one nested heading. <tt class="docutils literal"><span class="pre">toctree</span></tt> directives in
those documents are also taken into account.</li>
<li>Sphinx knows that the relative order of the documents <tt class="docutils literal"><span class="pre">intro</span></tt>,
<tt class="docutils literal"><span class="pre">strings</span></tt> and so forth, and it knows that they are children of the shown
document, the library index. From this information it generates “next
chapter”, “previous chapter” and “parent chapter” links.</li>
</ul>
<p><strong>Entries</strong></p>
<p>Document titles in the <a class="reference internal" href="#directive-toctree" title="toctree directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">toctree</span></tt></a> will be automatically read from the
title of the referenced document. If that isn’t what you want, you can
specify an explicit title and target using a similar syntax to reST
hyperlinks (and Sphinx’s <a class="reference internal" href="inline.html#xref-syntax"><em>cross-referencing syntax</em></a>). This
looks like:</p>
<div class="highlight-rst"><pre>.. toctree::
intro
All about strings <strings>
datatypes</pre>
</div>
<p>The second line above will link to the <tt class="docutils literal"><span class="pre">strings</span></tt> document, but will use the
title “All about strings” instead of the title of the <tt class="docutils literal"><span class="pre">strings</span></tt> document.</p>
<p>You can also add external links, by giving an HTTP URL instead of a document
name.</p>
<p><strong>Section numbering</strong></p>
<p>If you want to have section numbers even in HTML output, give the toctree a
<tt class="docutils literal"><span class="pre">numbered</span></tt> option. For example:</p>
<div class="highlight-rst"><pre>.. toctree::
:numbered:
foo
bar</pre>
</div>
<p>Numbering then starts at the heading of <tt class="docutils literal"><span class="pre">foo</span></tt>. Sub-toctrees are
automatically numbered (don’t give the <tt class="docutils literal"><span class="pre">numbered</span></tt> flag to those).</p>
<p>Numbering up to a specific depth is also possible, by giving the depth as a
numeric argument to <tt class="docutils literal"><span class="pre">numbered</span></tt>.</p>
<p><strong>Additional options</strong></p>
<p>If you want only the titles of documents in the tree to show up, not other
headings of the same level, you can use the <tt class="docutils literal"><span class="pre">titlesonly</span></tt> option:</p>
<div class="highlight-rst"><pre>.. toctree::
:titlesonly:
foo
bar</pre>
</div>
<p>You can use “globbing” in toctree directives, by giving the <tt class="docutils literal"><span class="pre">glob</span></tt> flag
option. All entries are then matched against the list of available
documents, and matches are inserted into the list alphabetically. Example:</p>
<div class="highlight-rst"><pre>.. toctree::
:glob:
intro*
recipe/*
*</pre>
</div>
<p>This includes first all documents whose names start with <tt class="docutils literal"><span class="pre">intro</span></tt>, then all
documents in the <tt class="docutils literal"><span class="pre">recipe</span></tt> folder, then all remaining documents (except the
one containing the directive, of course.) <a class="footnote-reference" href="#id4" id="id2">[2]</a></p>
<p>The special entry name <tt class="docutils literal"><span class="pre">self</span></tt> stands for the document containing the
toctree directive. This is useful if you want to generate a “sitemap” from
the toctree.</p>
<p>You can also give a “hidden” option to the directive, like this:</p>
<div class="highlight-rst"><pre>.. toctree::
:hidden:
doc_1
doc_2</pre>
</div>
<p>This will still notify Sphinx of the document hierarchy, but not insert links
into the document at the location of the directive – this makes sense if you
intend to insert these links yourself, in a different style, or in the HTML
sidebar.</p>
<p>In the end, all documents in the <a class="reference internal" href="../glossary.html#term-source-directory"><em class="xref std std-term">source directory</em></a> (or subdirectories)
must occur in some <tt class="docutils literal"><span class="pre">toctree</span></tt> directive; Sphinx will emit a warning if it
finds a file that is not included, because that means that this file will not
be reachable through standard navigation. Use <a class="reference internal" href="../config.html#confval-unused_docs"><tt class="xref std std-confval docutils literal"><span class="pre">unused_docs</span></tt></a> to
explicitly exclude documents from building, and <a class="reference internal" href="../config.html#confval-exclude_trees"><tt class="xref std std-confval docutils literal"><span class="pre">exclude_trees</span></tt></a> to
exclude whole directories.</p>
<p>The “master document” (selected by <a class="reference internal" href="../config.html#confval-master_doc"><tt class="xref std std-confval docutils literal"><span class="pre">master_doc</span></tt></a>) is the “root” of
the TOC tree hierarchy. It can be used as the documentation’s main page, or
as a “full table of contents” if you don’t give a <tt class="docutils literal"><span class="pre">maxdepth</span></tt> option.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.3: </span>Added “globbing” option.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.6: </span>Added “numbered” and “hidden” options as well as external links and
support for “self” references.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 1.0: </span>Added “titlesonly” option.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 1.1: </span>Added numeric argument to “numbered”.</p>
</dd></dl>
<div class="section" id="special-names">
<h2>Special names<a class="headerlink" href="#special-names" title="Permalink to this headline">¶</a></h2>
<p>Sphinx reserves some document names for its own use; you should not try to
create documents with these names – it will cause problems.</p>
<p>The special document names (and pages generated for them) are:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">genindex</span></tt>, <tt class="docutils literal"><span class="pre">modindex</span></tt>, <tt class="docutils literal"><span class="pre">search</span></tt></p>
<p>These are used for the general index, the Python module index, and the search
page, respectively.</p>
<p>The general index is populated with entries from modules, all index-generating
<a class="reference internal" href="../domains.html#basic-domain-markup"><em>object descriptions</em></a>, and from <a class="reference internal" href="misc.html#directive-index" title="index directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">index</span></tt></a>
directives.</p>
<p>The Python module index contains one entry per <a class="reference internal" href="../domains.html#directive-py:module" title="py:module directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">py:module</span></tt></a> directive.</p>
<p>The search page contains a form that uses the generated JSON search index and
JavaScript to full-text search the generated documents for search words; it
should work on every major browser that supports modern JavaScript.</p>
</li>
<li><p class="first">every name beginning with <tt class="docutils literal"><span class="pre">_</span></tt></p>
<p>Though only few such names are currently used by Sphinx, you should not create
documents or document-containing directories with such names. (Using <tt class="docutils literal"><span class="pre">_</span></tt> as
a prefix for a custom template directory is fine.)</p>
</li>
</ul>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id3" 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>The <tt class="docutils literal"><span class="pre">maxdepth</span></tt> option does not apply to the LaTeX writer, where the
whole table of contents will always be presented at the begin of the
document, and its depth is controlled by the <tt class="docutils literal"><span class="pre">tocdepth</span></tt> counter, which
you can reset in your <a class="reference internal" href="../config.html#confval-latex_preamble"><tt class="xref std std-confval docutils literal"><span class="pre">latex_preamble</span></tt></a> config value using
e.g. <tt class="docutils literal"><span class="pre">\setcounter{tocdepth}{2}</span></tt>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>A note on available globbing syntax: you can use the standard shell
constructs <tt class="docutils literal"><span class="pre">*</span></tt>, <tt class="docutils literal"><span class="pre">?</span></tt>, <tt class="docutils literal"><span class="pre">[...]</span></tt> and <tt class="docutils literal"><span class="pre">[!...]</span></tt> with the feature that
these all don’t match slashes. A double star <tt class="docutils literal"><span class="pre">**</span></tt> can be used to match
any sequence of characters <em>including</em> slashes.</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="para.html" title="Paragraph-level markup"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Sphinx Markup Constructs"
>previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="index.html" >Sphinx Markup Constructs</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
>
133
