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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
.. highlight:: rest
Miscellaneous markup
====================
.. _metadata:
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 at the very 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*, the docinfo is used as metadata, too, but not displayed
in the output.
At the moment, these metadata fields are recognized:
``tocdepth``
The maximum depth for a table of contents of this file.
.. versionadded:: 0.4
``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.
.. versionadded:: 1.0
Meta-information markup
-----------------------
.. rst:directive:: .. sectionauthor:: name <email>
Identifies the author of the current section. The argument should include
the author's name such that it can be used for presentation and email
address. The domain name portion of the address should be lower case.
Example::
.. sectionauthor:: Guido van Rossum <guido@python.org>
By default, this markup isn't reflected in the output in any way (it helps
keep track of contributions), but you can set the configuration value
:confval:`show_authors` to True to make them produce a paragraph in the
output.
.. rst:directive:: .. codeauthor:: name <email>
The :rst:dir:`codeauthor` directive, which can appear multiple times, names the
authors of the described code, just like :rst:dir:`sectionauthor` names the
author(s) of a piece of documentation. It too only produces output if the
:confval:`show_authors` configuration value is True.
.. _tags:
Including content based on tags
-------------------------------
.. rst:directive:: .. only:: <expression>
Include the content of the directive only if the *expression* is true. The
expression should consist of tags, like this::
.. only:: html and draft
Undefined tags are false, defined tags (via the ``-t`` command-line option or
within :file:`conf.py`) are true. Boolean expressions, also using
parentheses (like ``html and (latex or draft)`` are supported.
The format of the current builder (``html``, ``latex`` or ``text``) is always
set as a tag.
.. versionadded:: 0.6
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:
.. rst:directive:: .. tabularcolumns:: column spec
This directive gives a "column spec" for the next table occurring in the
source file. The spec is the second argument to the LaTeX ``tabulary``
package's environment (which Sphinx uses to translate tables). It can have
values like ::
|l|l|l|
which means three left-adjusted, nonbreaking columns. For columns with
longer text that should automatically be broken, use either the standard
``p{width}`` construct, or tabulary's automatic specifiers:
+-----+------------------------------------------+
|``L``| ragged-left column with automatic width |
+-----+------------------------------------------+
|``R``| ragged-right column with automatic width |
+-----+------------------------------------------+
|``C``| centered column with automatic width |
+-----+------------------------------------------+
|``J``| justified column with automatic width |
+-----+------------------------------------------+
The automatic width is determined by rendering the content in the table, and
scaling them according to their share of the total width.
By default, Sphinx uses a table layout with ``L`` for every column.
.. versionadded:: 0.3
.. warning::
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 :rst:dir:`tabularcolumns` directive to get finer control
over such tables.
|
