Source

sphinx / doc / markup / misc.rst

Full commit

Miscellaneous markup

File-wide metadata

reST has the concept of "field lists"; these are a sequence of fields marked up like this:

:fieldname: Field content

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. In Sphinx, 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.

At the moment, these metadata fields are recognized:

tocdepth
The maximum depth for a table of contents of this file.
nocomments
If set, the web application won't display a comment form for a page generated from this source file.
orphan
If set, warnings about this file not being included in any toctree will be suppressed.

Meta-information markup

Index-generating markup

Sphinx automatically creates index entries from all object descriptions (like functions, classes or attributes) like discussed in :ref:`domains`.

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.

Including content based on tags

Tables

Use :ref:`standard reStructuredText tables <rst-tables>`. 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:

Warning

Tables that contain list-like elements such as object descriptions, blockquotes or any kind of lists cannot be set out of the box with tabulary. They are therefore set with the standard LaTeX tabular environment if you don't give a tabularcolumns directive. If you do, the table will be set with tabulary, but you must use the p{width} construct for the columns that contain these elements.

Literal blocks do not work with tabulary at all, so tables containing a literal block are always set with tabular. Also, the verbatim environment used for literal blocks only works in p{width} columns, which means that by default, Sphinx generates such column specs for such tables. Use the :rst:dir:`tabularcolumns` directive to get finer control over such tables.

Footnotes

[1]For most builders name and format are the same. At the moment only builders derived from the html builder distinguish between the builder format and the builder name.