summaryrefslogtreecommitdiffstats
path: root/doc/usage/restructuredtext/field-lists.rst
blob: 62dad5ca83cd44e9682c44ad85c1bc4571fc9c09 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
.. highlight:: rst

===========
Field Lists
===========

:ref:`As previously discussed <rst-field-lists>`, field lists are sequences of
fields marked up like this::

    :fieldname: Field content

Sphinx extends standard docutils behavior for field lists and adds some extra
functionality that is covered in this section.

.. note::

    The values of field lists will be parsed as
    strings. You cannot use Python collections such as lists or dictionaries.


.. _metadata:

File-wide metadata
------------------

A field list near the top of a file is normally parsed by docutils as the
*docinfo* and shown on the page.  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.

.. note::

   A field list appearing after the document title *will* be part of the
   *docinfo* as normal and will be displayed in the output.


Special metadata fields
-----------------------

Sphinx provides custom behavior for bibliographic fields compared to docutils.

At the moment, these metadata fields are recognized:

``tocdepth``
   The maximum depth for a table of contents of this file. ::

       :tocdepth: 2

   .. note::

      This metadata effects to the depth of local toctree.  But it does not
      effect to the depth of *global* toctree.  So this would not be change
      the sidebar of some themes which uses global one.

   .. 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

``nosearch``
   If set, full text search for this file is disabled. ::

       :nosearch:

   .. note:: object search is still available even if ``nosearch`` option is set.

   .. versionadded:: 3.0