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:

:Field name: Field content

A field list at the very top of a file is parsed as the "docinfo", which in normal documents can be used to record the author, date of publication and other metadata. In Sphinx, the docinfo is used as metadata, too, but not displayed in the output.

At the moment, these metadata fields are recognized:

The maximum depth for a table of contents of this file.
If set, the web application won't display a comment form for a page generated from this source file.

Meta-information markup


Use standard reStructuredText 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:


Tables that contain literal blocks cannot be set with tabulary. They are therefore set with the standard LaTeX tabular environment. 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 :dir:`tabularcolumns` directive to get finer control over such tables.