2018-04-14 09:15:31 -05:00
|
|
|
.. highlight:: rst
|
2017-11-03 09:35:20 -05:00
|
|
|
|
|
|
|
|
===========
|
|
|
|
|
Field Lists
|
|
|
|
|
===========
|
|
|
|
|
|
|
|
|
|
:ref:`As previously discussed <rst-field-lists>`, field lists are sequences of
|
|
|
|
|
fields marked up like this::
|
|
|
|
|
|
|
|
|
|
:fieldname: Field content
|
|
|
|
|
|
|
|
|
|
Sphinx provides custom behavior for bibliographic fields compared to docutils.
|
|
|
|
|
|
|
|
|
|
.. _metadata:
|
|
|
|
|
|
|
|
|
|
File-wide metadata
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
A field list near the top of a file is normally parsed by docutils as the
|
|
|
|
|
*docinfo* which is generally used to record the author, date of publication and
|
|
|
|
|
other metadata. However, 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. ::
|
|
|
|
|
|
|
|
|
|
:tocdepth: 2
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 0.4
|
|
|
|
|
|
|
|
|
|
``nocomments``
|
|
|
|
|
If set, the web application won't display a comment form for a page
|
|
|
|
|
generated from this source file. ::
|
|
|
|
|
|
|
|
|
|
:nocomments:
|
|
|
|
|
|
|
|
|
|
``orphan``
|
|
|
|
|
If set, warnings about this file not being included in any toctree will be
|
|
|
|
|
suppressed. ::
|
|
|
|
|
|
|
|
|
|
:orphan:
|
|
|
|
|
|
|
|
|
|
.. versionadded:: 1.0
|
