<!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 v1.0.7 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.0.7',
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 v1.0.7 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Sphinx v1.0.7 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="#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" size="18" />
<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="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>
<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><td><tt class="docutils literal"><span class="pre">L</span></tt></td>
<td>ragged-left column with automatic width</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">R</span></tt></td>
<td>ragged-right column with automatic width</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">C</span></tt></td>
<td>centered column with automatic width</td>
</tr>
<tr><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.0.7.
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
2b39e69e45f9a0b2b3aece7339c56216
>
files
>
110
