<!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>Miscellaneous markup — 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="Sphinx Domains" href="../domains.html" />
<link rel="prev" title="Inline markup" href="inline.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="../domains.html" title="Sphinx Domains"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="inline.html" title="Inline markup"
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="#">Miscellaneous markup</a><ul>
<li><a class="reference internal" href="#file-wide-metadata">File-wide metadata</a></li>
<li><a class="reference internal" href="#meta-information-markup">Meta-information markup</a></li>
<li><a class="reference internal" href="#index-generating-markup">Index-generating markup</a></li>
<li><a class="reference internal" href="#including-content-based-on-tags">Including content based on tags</a></li>
<li><a class="reference internal" href="#tables">Tables</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="inline.html"
title="previous chapter">Inline markup</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../domains.html"
title="next chapter">Sphinx Domains</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/markup/misc.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="miscellaneous-markup">
<h1>Miscellaneous markup<a class="headerlink" href="#miscellaneous-markup" title="Permalink to this headline">¶</a></h1>
<div class="section" id="file-wide-metadata">
<span id="metadata"></span><h2>File-wide metadata<a class="headerlink" href="#file-wide-metadata" title="Permalink to this headline">¶</a></h2>
<p>reST has the concept of “field lists”; these are a sequence of fields marked up
like this:</p>
<div class="highlight-rest"><pre>:fieldname: Field content</pre>
</div>
<p>A field list near the top of a file is parsed by docutils as the “docinfo”
which is normally used to record the author, date of publication and other
metadata. <em>In Sphinx</em>, a field list preceding any other markup is moved from
the docinfo to the Sphinx environment as document metadata and is not displayed
in the output; a field list appearing after the document title will be part of
the docinfo as normal and will be displayed in the output.</p>
<p>At the moment, these metadata fields are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">tocdepth</span></tt></dt>
<dd><p class="first">The maximum depth for a table of contents of this file.</p>
<p class="last versionadded">
<span class="versionmodified">New in version 0.4.</span></p>
</dd>
<dt><tt class="docutils literal"><span class="pre">nocomments</span></tt></dt>
<dd>If set, the web application won’t display a comment form for a page generated
from this source file.</dd>
<dt><tt class="docutils literal"><span class="pre">orphan</span></tt></dt>
<dd><p class="first">If set, warnings about this file not being included in any toctree will be
suppressed.</p>
<p class="last versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
</dd>
</dl>
</div>
<div class="section" id="meta-information-markup">
<h2>Meta-information markup<a class="headerlink" href="#meta-information-markup" title="Permalink to this headline">¶</a></h2>
<dl class="directive">
<dt id="directive-sectionauthor">
<tt class="descname">.. sectionauthor::</tt><tt class="descclassname"> name <email></tt><a class="headerlink" href="#directive-sectionauthor" title="Permalink to this definition">¶</a></dt>
<dd><p>Identifies the author of the current section. The argument should include
the author’s name such that it can be used for presentation and email
address. The domain name portion of the address should be lower case.
Example:</p>
<div class="highlight-rest"><pre>.. sectionauthor:: Guido van Rossum <guido@python.org></pre>
</div>
<p>By default, this markup isn’t reflected in the output in any way (it helps
keep track of contributions), but you can set the configuration value
<a class="reference internal" href="../config.html#confval-show_authors"><tt class="xref std std-confval docutils literal"><span class="pre">show_authors</span></tt></a> to True to make them produce a paragraph in the
output.</p>
</dd></dl>
<dl class="directive">
<dt id="directive-codeauthor">
<tt class="descname">.. codeauthor::</tt><tt class="descclassname"> name <email></tt><a class="headerlink" href="#directive-codeauthor" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="#directive-codeauthor" title="codeauthor directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">codeauthor</span></tt></a> directive, which can appear multiple times, names the
authors of the described code, just like <a class="reference internal" href="#directive-sectionauthor" title="sectionauthor directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">sectionauthor</span></tt></a> names the
author(s) of a piece of documentation. It too only produces output if the
<a class="reference internal" href="../config.html#confval-show_authors"><tt class="xref std std-confval docutils literal"><span class="pre">show_authors</span></tt></a> configuration value is True.</p>
</dd></dl>
</div>
<div class="section" id="index-generating-markup">
<h2>Index-generating markup<a class="headerlink" href="#index-generating-markup" title="Permalink to this headline">¶</a></h2>
<p>Sphinx automatically creates index entries from all object descriptions (like
functions, classes or attributes) like discussed in <a class="reference internal" href="../domains.html#domains"><em>Sphinx Domains</em></a>.</p>
<p>However, there is also explicit markup available, to make the index more
comprehensive and enable index entries in documents where information is not
mainly contained in information units, such as the language reference.</p>
<dl class="directive">
<dt id="directive-index">
<tt class="descname">.. index::</tt><tt class="descclassname"> <entries></tt><a class="headerlink" href="#directive-index" title="Permalink to this definition">¶</a></dt>
<dd><p>This directive contains one or more index entries. Each entry consists of a
type and a value, separated by a colon.</p>
<p>For example:</p>
<div class="highlight-rest"><pre>.. index::
single: execution; context
module: __main__
module: sys
triple: module; search; path
The execution context
---------------------
...</pre>
</div>
<p>This directive contains five entries, which will be converted to entries in
the generated index which link to the exact location of the index statement
(or, in case of offline media, the corresponding page number).</p>
<p>Since index directives generate cross-reference targets at their location in
the source, it makes sense to put them <em>before</em> the thing they refer to –
e.g. a heading, as in the example above.</p>
<p>The possible entry types are:</p>
<dl class="docutils">
<dt>single</dt>
<dd>Creates a single index entry. Can be made a subentry by separating the
subentry text with a semicolon (this notation is also used below to
describe what entries are created).</dd>
<dt>pair</dt>
<dd><tt class="docutils literal"><span class="pre">pair:</span> <span class="pre">loop;</span> <span class="pre">statement</span></tt> is a shortcut that creates two index entries,
namely <tt class="docutils literal"><span class="pre">loop;</span> <span class="pre">statement</span></tt> and <tt class="docutils literal"><span class="pre">statement;</span> <span class="pre">loop</span></tt>.</dd>
<dt>triple</dt>
<dd>Likewise, <tt class="docutils literal"><span class="pre">triple:</span> <span class="pre">module;</span> <span class="pre">search;</span> <span class="pre">path</span></tt> is a shortcut that creates
three index entries, which are <tt class="docutils literal"><span class="pre">module;</span> <span class="pre">search</span> <span class="pre">path</span></tt>, <tt class="docutils literal"><span class="pre">search;</span> <span class="pre">path,</span>
<span class="pre">module</span></tt> and <tt class="docutils literal"><span class="pre">path;</span> <span class="pre">module</span> <span class="pre">search</span></tt>.</dd>
<dt>see</dt>
<dd><tt class="docutils literal"><span class="pre">see:</span> <span class="pre">entry;</span> <span class="pre">other</span></tt> creates an index entry that refers from <tt class="docutils literal"><span class="pre">entry</span></tt> to
<tt class="docutils literal"><span class="pre">other</span></tt>.</dd>
<dt>seealso</dt>
<dd>Like <tt class="docutils literal"><span class="pre">see</span></tt>, but inserts “see also” instead of “see”.</dd>
<dt>module, keyword, operator, object, exception, statement, builtin</dt>
<dd>These all create two index entries. For example, <tt class="docutils literal"><span class="pre">module:</span> <span class="pre">hashlib</span></tt>
creates the entries <tt class="docutils literal"><span class="pre">module;</span> <span class="pre">hashlib</span></tt> and <tt class="docutils literal"><span class="pre">hashlib;</span> <span class="pre">module</span></tt>. (These
are Python-specific and therefore deprecated.)</dd>
</dl>
<p>You can mark up “main” index entries by prefixing them with an exclamation
mark. The references to “main” entries are emphasized in the generated
index. For example, if two pages contain</p>
<div class="highlight-rest"><pre>.. index:: Python</pre>
</div>
<p>and one page contains</p>
<div class="highlight-rest"><pre>.. index:: ! Python</pre>
</div>
<p>then the backlink to the latter page is emphasized among the three backlinks.</p>
<p>For index directives containing only “single” entries, there is a shorthand
notation:</p>
<div class="highlight-rest"><pre>.. index:: BNF, grammar, syntax, notation</pre>
</div>
<p>This creates four index entries.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 1.1: </span>Added <tt class="docutils literal"><span class="pre">see</span></tt> and <tt class="docutils literal"><span class="pre">seealso</span></tt> types, as well as marking main entries.</p>
</dd></dl>
<dl class="role">
<dt id="role-index">
<tt class="descname">:index:</tt><a class="headerlink" href="#role-index" title="Permalink to this definition">¶</a></dt>
<dd><p>While the <a class="reference internal" href="#directive-index" title="index directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">index</span></tt></a> directive is a block-level markup and links to the
beginning of the next paragraph, there is also a corresponding role that sets
the link target directly where it is used.</p>
<p>The content of the role can be a simple phrase, which is then kept in the
text and used as an index entry. It can also be a combination of text and
index entry, styled like with explicit targets of cross-references. In that
case, the “target” part can be a full entry as described for the directive
above. For example:</p>
<div class="highlight-rest"><pre>This is a normal reST :index:`paragraph` that contains several
:index:`index entries <pair: index; entry>`.</pre>
</div>
<p class="versionadded">
<span class="versionmodified">New in version 1.1.</span></p>
</dd></dl>
</div>
<div class="section" id="including-content-based-on-tags">
<span id="tags"></span><h2>Including content based on tags<a class="headerlink" href="#including-content-based-on-tags" title="Permalink to this headline">¶</a></h2>
<dl class="directive">
<dt id="directive-only">
<tt class="descname">.. only::</tt><tt class="descclassname"> <expression></tt><a class="headerlink" href="#directive-only" title="Permalink to this definition">¶</a></dt>
<dd><p>Include the content of the directive only if the <em>expression</em> is true. The
expression should consist of tags, like this:</p>
<div class="highlight-rest"><pre>.. only:: html and draft</pre>
</div>
<p>Undefined tags are false, defined tags (via the <tt class="docutils literal"><span class="pre">-t</span></tt> command-line option or
within <tt class="file docutils literal"><span class="pre">conf.py</span></tt>) are true. Boolean expressions, also using
parentheses (like <tt class="docutils literal"><span class="pre">html</span> <span class="pre">and</span> <span class="pre">(latex</span> <span class="pre">or</span> <span class="pre">draft)</span></tt>) are supported.</p>
<p>The format of the current builder (<tt class="docutils literal"><span class="pre">html</span></tt>, <tt class="docutils literal"><span class="pre">latex</span></tt> or <tt class="docutils literal"><span class="pre">text</span></tt>) is always
set as a tag.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Due to docutils’ specifics of parsing of directive content, you cannot put
a section with the same level as the main document heading inside an
<tt class="docutils literal"><span class="pre">only</span></tt> directive. Such sections will appear to be ignored in the parsed
document.</p>
</div>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
</dd></dl>
</div>
<div class="section" id="tables">
<h2>Tables<a class="headerlink" href="#tables" title="Permalink to this headline">¶</a></h2>
<p>Use <a class="reference internal" href="../rest.html#rst-tables"><em>standard reStructuredText tables</em></a>. They work fine in
HTML output, however there are some gotchas when using tables in LaTeX: the
column width is hard to determine correctly automatically. For this reason, the
following directive exists:</p>
<dl class="directive">
<dt id="directive-tabularcolumns">
<tt class="descname">.. tabularcolumns::</tt><tt class="descclassname"> column spec</tt><a class="headerlink" href="#directive-tabularcolumns" title="Permalink to this definition">¶</a></dt>
<dd><p>This directive gives a “column spec” for the next table occurring in the
source file. The spec is the second argument to the LaTeX <tt class="docutils literal"><span class="pre">tabulary</span></tt>
package’s environment (which Sphinx uses to translate tables). It can have
values like</p>
<div class="highlight-rest"><pre>|l|l|l|</pre>
</div>
<p>which means three left-adjusted, nonbreaking columns. For columns with
longer text that should automatically be broken, use either the standard
<tt class="docutils literal"><span class="pre">p{width}</span></tt> construct, or tabulary’s automatic specifiers:</p>
<table border="1" class="docutils">
<colgroup>
<col width="11%" />
<col width="89%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">L</span></tt></td>
<td>ragged-left column with automatic width</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">R</span></tt></td>
<td>ragged-right column with automatic width</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">C</span></tt></td>
<td>centered column with automatic width</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">J</span></tt></td>
<td>justified column with automatic width</td>
</tr>
</tbody>
</table>
<p>The automatic width is determined by rendering the content in the table, and
scaling them according to their share of the total width.</p>
<p>By default, Sphinx uses a table layout with <tt class="docutils literal"><span class="pre">L</span></tt> for every column.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.3.</span></p>
</dd></dl>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>Tables that contain list-like elements such as object descriptions,
blockquotes or any kind of lists cannot be set out of the box with
<tt class="docutils literal"><span class="pre">tabulary</span></tt>. They are therefore set with the standard LaTeX <tt class="docutils literal"><span class="pre">tabular</span></tt>
environment if you don’t give a <tt class="docutils literal"><span class="pre">tabularcolumns</span></tt> directive. If you do, the
table will be set with <tt class="docutils literal"><span class="pre">tabulary</span></tt>, but you must use the <tt class="docutils literal"><span class="pre">p{width}</span></tt>
construct for the columns that contain these elements.</p>
<p class="last">Literal blocks do not work with <tt class="docutils literal"><span class="pre">tabulary</span></tt> at all, so tables containing a
literal block are always set with <tt class="docutils literal"><span class="pre">tabular</span></tt>. Also, the verbatim
environment used for literal blocks only works in <tt class="docutils literal"><span class="pre">p{width}</span></tt> columns, which
means that by default, Sphinx generates such column specs for such tables.
Use the <a class="reference internal" href="#directive-tabularcolumns" title="tabularcolumns directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">tabularcolumns</span></tt></a> directive to get finer control over such
tables.</p>
</div>
</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="../domains.html" title="Sphinx Domains"
>next</a> |</li>
<li class="right" >
<a href="inline.html" title="Inline markup"
>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
>
131
