blob: d352633f46b8a4b9169710fbac440b1af4eb3f4d (
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 affects the depth of the local toctree. But it does not
affect the depth of the *global* toctree. So this does not change
the sidebar of themes that use the global toctree.
.. 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
|
