Directives¶
As previously discussed, a directive is a generic block of explicit markup. While Docutils provides a number of directives, Sphinx provides many more and uses directives as one of the primary extension mechanisms.
See Domains for roles added by domains.
Ver también
Refer to the reStructuredText Primer for an overview of the directives provided by Docutils.
Table of contents¶
Since reST does not have facilities to interconnect several documents, or split
documents into multiple output files, Sphinx uses a custom directive to add
relations between the single files the documentation is made of, as well as
tables of contents. The toctree
directive is the central element.
Nota
Simple «inclusion» of one file in another can be done with the include directive.
Nota
For local tables of contents, use the standard reST contents directive.
-
.. toctree::
¶ This directive inserts a «TOC tree» at the current location, using the individual TOCs (including «sub-TOC trees») of the documents given in the directive body. Relative document names (not beginning with a slash) are relative to the document the directive occurs in, absolute names are relative to the source directory. A numeric
maxdepth
option may be given to indicate the depth of the tree; by default, all levels are included. [1]Consider this example (taken from the Python docs” library reference index):
.. toctree:: :maxdepth: 2 intro strings datatypes numeric (many more documents listed here)
This accomplishes two things:
- Tables of contents from all those documents are inserted, with a maximum
depth of two, that means one nested heading.
toctree
directives in those documents are also taken into account. - Sphinx knows the relative order of the documents
intro
,strings
and so forth, and it knows that they are children of the shown document, the library index. From this information it generates «next chapter», «previous chapter» and «parent chapter» links.
Entries
Document titles in the
toctree
will be automatically read from the title of the referenced document. If that isn’t what you want, you can specify an explicit title and target using a similar syntax to reST hyperlinks (and Sphinx’s cross-referencing syntax). This looks like:.. toctree:: intro All about strings <strings> datatypes
The second line above will link to the
strings
document, but will use the title «All about strings» instead of the title of thestrings
document.You can also add external links, by giving an HTTP URL instead of a document name.
Section numbering
If you want to have section numbers even in HTML output, give the toplevel toctree a
numbered
option. For example:.. toctree:: :numbered: foo bar
Numbering then starts at the heading of
foo
. Sub-toctrees are automatically numbered (don’t give thenumbered
flag to those).Numbering up to a specific depth is also possible, by giving the depth as a numeric argument to
numbered
.Additional options
You can use
caption
option to provide a toctree caption and you can usename
option to provide implicit target name that can be referenced by usingref
:.. toctree:: :caption: Table of Contents :name: mastertoc foo
If you want only the titles of documents in the tree to show up, not other headings of the same level, you can use the
titlesonly
option:.. toctree:: :titlesonly: foo bar
You can use «globbing» in toctree directives, by giving the
glob
flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically. Example:.. toctree:: :glob: intro* recipe/* *
This includes first all documents whose names start with
intro
, then all documents in therecipe
folder, then all remaining documents (except the one containing the directive, of course.) [2]The special entry name
self
stands for the document containing the toctree directive. This is useful if you want to generate a «sitemap» from the toctree.You can use the
reversed
flag option to reverse the order of the entries in the list. This can be useful when using theglob
flag option to reverse the ordering of the files. Example:.. toctree:: :glob: :reversed: recipe/*
You can also give a «hidden» option to the directive, like this:
.. toctree:: :hidden: doc_1 doc_2
This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive – this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.
In cases where you want to have only one top-level toctree and hide all other lower level toctrees you can add the «includehidden» option to the top-level toctree entry:
.. toctree:: :includehidden: doc_1 doc_2
All other toctree entries can then be eliminated by the «hidden» option.
In the end, all documents in the source directory (or subdirectories) must occur in some
toctree
directive; Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not be reachable through standard navigation.Use
exclude_patterns
to explicitly exclude documents or directories from building completely. Use the «orphan» metadata to let a document be built, but notify Sphinx that it is not reachable via a toctree.The «master document» (selected by
master_doc
) is the «root» of the TOC tree hierarchy. It can be used as the documentation’s main page, or as a «full table of contents» if you don’t give amaxdepth
option.Distinto en la versión 0.3: Added «globbing» option.
Distinto en la versión 0.6: Added «numbered» and «hidden» options as well as external links and support for «self» references.
Distinto en la versión 1.0: Added «titlesonly» option.
Distinto en la versión 1.1: Added numeric argument to «numbered».
Distinto en la versión 1.2: Added «includehidden» option.
Distinto en la versión 1.3: Added «caption» and «name» option.
- Tables of contents from all those documents are inserted, with a maximum
depth of two, that means one nested heading.
Special names¶
Sphinx reserves some document names for its own use; you should not try to create documents with these names – it will cause problems.
The special document names (and pages generated for them) are:
genindex
,modindex
,search
These are used for the general index, the Python module index, and the search page, respectively.
The general index is populated with entries from modules, all index-generating object descriptions, and from
index
directives.The Python module index contains one entry per
py:module
directive.The search page contains a form that uses the generated JSON search index and JavaScript to full-text search the generated documents for search words; it should work on every major browser that supports modern JavaScript.
every name beginning with
_
Though only few such names are currently used by Sphinx, you should not create documents or document-containing directories with such names. (Using
_
as a prefix for a custom template directory is fine.)
Advertencia
Be careful with unusual characters in filenames. Some formats may interpret these characters in unexpected ways:
- Do not use the colon
:
for HTML based formats. Links to other parts may not work. - Do not use the plus
+
for the ePub format. Some resources may not be found.
Paragraph-level markup¶
These directives create short paragraphs and can be used inside information units as well as normal text.
-
.. note::
An especially important bit of information about an API that a user should be aware of when using whatever bit of API the note pertains to. The content of the directive should be written in complete sentences and include all appropriate punctuation.
Example:
.. note:: This function is not suitable for sending spam e-mails.
-
.. warning::
An important bit of information about an API that a user should be very aware of when using whatever bit of API the warning pertains to. The content of the directive should be written in complete sentences and include all appropriate punctuation. This differs from
note
in that it is recommended overnote
for information regarding security.
-
.. versionadded::
version
¶ This directive documents the version of the project which added the described feature to the library or C API. When this applies to an entire module, it should be placed at the top of the module section before any prose.
The first argument must be given and is the version in question; you can add a second argument consisting of a brief explanation of the change.
Example:
.. versionadded:: 2.5 The *spam* parameter.
Note that there must be no blank line between the directive head and the explanation; this is to make these blocks visually continuous in the markup.
-
.. versionchanged::
version
¶ Similar to
versionadded
, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.).
-
.. deprecated::
version
¶ Similar to
versionchanged
, but describes when the feature was deprecated. An explanation can also be given, for example to inform the reader what should be used instead. Example:.. deprecated:: 3.1 Use :func:`spam` instead.
-
.. seealso::
¶ Many sections include a list of references to module documentation or external documents. These lists are created using the
seealso
directive.The
seealso
directive is typically placed in a section just before any subsections. For the HTML output, it is shown boxed off from the main flow of the text.The content of the
seealso
directive should be a reST definition list. Example:.. seealso:: Module :py:mod:`zipfile` Documentation of the :py:mod:`zipfile` standard module. `GNU tar manual, Basic Tar Format <http://link>`_ Documentation for tar archive files, including GNU tar extensions.
There’s also a «short form» allowed that looks like this:
.. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
Nuevo en la versión 0.5: The short form.
-
.. rubric::
title
¶ This directive creates a paragraph heading that is not used to create a table of contents node.
Nota
If the title of the rubric is «Footnotes» (or the selected language’s equivalent), this rubric is ignored by the LaTeX writer, since it is assumed to only contain footnote definitions and therefore would create an empty heading.
-
.. centered::
¶ This directive creates a centered boldfaced line of text. Use it as follows:
.. centered:: LICENSE AGREEMENT
Obsoleto desde la versión 1.1: This presentation-only directive is a legacy from older versions. Use a
rst-class
directive instead and add an appropriate style.
-
.. hlist::
¶ This directive must contain a bullet list. It will transform it into a more compact list by either distributing more than one item horizontally, or reducing spacing between items, depending on the builder.
For builders that support the horizontal distribution, there is a
columns
option that specifies the number of columns; it defaults to 2. Example:.. hlist:: :columns: 3 * A list of * short items * that should be * displayed * horizontally
Nuevo en la versión 0.6.
Showing code examples¶
There are multiple ways to show syntax-highlighted literal code blocks in
Sphinx: using reST doctest blocks; using reST
literal blocks, optionally in combination with the
highlight
directive; using the code-block
directive; and
using the literalinclude
directive. Doctest blocks can only be used
to show interactive Python sessions, while the remaining three can be used for
other languages. Of these three, literal blocks are useful when an entire
document, or at least large sections of it, use code blocks with the same
syntax and which should be styled in the same manner. On the other hand, the
code-block
directive makes more sense when you want more fine-tuned
control over the styling of each block or when you have a document containing
code blocks using multiple varied syntaxes. Finally, the
literalinclude
directive is useful for including entire code files
in your documentation.
In all cases, Syntax highlighting is provided by Pygments. When using literal blocks, this is configured using
any highlight
directives in the source file. When a highlight
directive is encountered, it is used until the next highlight
directive is
encountered. If there is no highlight
directive in the file, the global
highlighting language is used. This defaults to python
but can be
configured using the highlight_language
config value. The following
values are supported:
none
(no highlighting)default
(similar topython3
but with a fallback tonone
without warning highlighting fails; the default whenhighlight_language
isn’t set)guess
(let Pygments guess the lexer based on contents, only works with certain well-recognizable languages)python
rest
c
- … and any other lexer alias that Pygments supports
If highlighting with the selected language fails (i.e. Pygments emits an «Error» token), the block is not highlighted in any way.
Importante
The list of lexer aliases supported is tied to the Pygment version. If you want to ensure consistent highlighting, you should fix your version of Pygments.
-
.. highlight::
language
¶ Example:
.. highlight:: c
This language is used until the next
highlight
directive is encountered. As discussed previously, language can be any lexer alias supported by Pygments.Additional options
Pygments can generate line numbers for code blocks. To enable this, use the
linenothreshold
option... highlight:: python :linenothreshold: 5
This will produce line numbers for all code blocks longer than five lines.
-
.. code-block::
language
¶ Example:
.. code-block:: ruby Some Ruby code.
The directive’s alias name
sourcecode
works as well. As withhighlight
’slanguage
option,language
can be any lexer alias supported by Pygments.Additional options
Pygments can generate line numbers for code blocks. To enable this for, use the
linenos
flag option... code-block:: ruby :linenos: Some more Ruby code.
The first line number can be selected with the
lineno-start
option. If present,linenos
flag is automatically activated:.. code-block:: ruby :lineno-start: 10 Some more Ruby code, with line numbering starting at 10.
Additionally, an
emphasize-lines
option can be given to have Pygments emphasize particular lines:.. code-block:: python :emphasize-lines: 3,5 def some_function(): interesting = False print 'This line is highlighted.' print 'This one is not...' print '...but this one is.'
A
caption
option can be given to show that name before the code block. Aname
option can be provided implicit target name that can be referenced by usingref
. For example:.. code-block:: python :caption: this.py :name: this-py print 'Explicit is better than implicit.'
A
dedent
option can be given to strip indentation characters from the code block. For example:.. code-block:: ruby :dedent: 4 some ruby code
Distinto en la versión 1.1: The
emphasize-lines
option has been added.Distinto en la versión 1.3: The
lineno-start
,caption
,name
anddedent
options have been added.Distinto en la versión 1.6.6: LaTeX supports the
emphasize-lines
option.
-
.. literalinclude::
filename
¶ Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the
literalinclude
directive. [3] For example, to include the Python source fileexample.py
, use:.. literalinclude:: example.py
The file name is usually relative to the current file’s path. However, if it is absolute (starting with
/
), it is relative to the top source directory.Additional options
Like
code-block
, the directive supports thelinenos
flag option to switch on line numbers, thelineno-start
option to select the first line number, theemphasize-lines
option to emphasize particular lines, thename
option to provide an implicit target name, thededent
option to strip indentation characters for the code block, and alanguage
option to select a language different from the current file’s standard language. In addition, it supports thecaption
option; however, this can be provided with no argument to use the filename as the caption. Example with options:.. literalinclude:: example.rb :language: ruby :emphasize-lines: 12,15-18 :linenos:
Tabs in the input are expanded if you give a
tab-width
option with the desired tab width.Include files are assumed to be encoded in the
source_encoding
. If the file has a different encoding, you can specify it with theencoding
option:.. literalinclude:: example.py :encoding: latin-1
The directive also supports including only parts of the file. If it is a Python module, you can select a class, function or method to include using the
pyobject
option:.. literalinclude:: example.py :pyobject: Timer.start
This would only include the code lines belonging to the
start()
method in theTimer
class within the file.Alternately, you can specify exactly which lines to include by giving a
lines
option:.. literalinclude:: example.py :lines: 1,3,5-10,20-
This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.
Another way to control which part of the file is included is to use the
start-after
andend-before
options (or only one of them). Ifstart-after
is given as a string option, only lines that follow the first line containing that string are included. Ifend-before
is given as a string option, only lines that precede the first lines containing that string are included. Thestart-at
andend-at
options behave in a similar way, but the lines containing the matched string are included.With lines selected using
start-after
it is still possible to uselines
, the first allowed line having by convention the line number1
.When lines have been selected in any of the ways described above, the line numbers in
emphasize-lines
refer to those selected lines, counted consecutively starting at1
.When specifying particular parts of a file to display, it can be useful to display the original line numbers. This can be done using the
lineno-match
option, which is however allowed only when the selection consists of contiguous lines.You can prepend and/or append a line to the included code, using the
prepend
andappend
option, respectively. This is useful e.g. for highlighting PHP code that doesn’t include the<?php
/?>
markers.If you want to show the diff of the code, you can specify the old file by giving a
diff
option:.. literalinclude:: example.py :diff: example.py.orig
This shows the diff between
example.py
andexample.py.orig
with unified diff format.Distinto en la versión 0.4.3: Added the
encoding
option.Distinto en la versión 0.6: Added the
pyobject
,lines
,start-after
andend-before
options, as well as support for absolute filenames.Distinto en la versión 1.0: Added the
prepend
,append
, andtab-width
options.Distinto en la versión 1.3: Added the
diff
,lineno-match
,caption
,name
, anddedent
options.Distinto en la versión 1.5: Added the
start-at
, andend-at
options.Distinto en la versión 1.6: With both
start-after
andlines
in use, the first line as perstart-after
is considered to be with line number1
forlines
.
Glossary¶
-
.. glossary::
This directive must contain a reST definition-list-like markup with terms and definitions. The definitions will then be referenceable with the
term
role. Example:.. glossary:: environment A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents. source directory The directory which, including its subdirectories, contains all source files for one Sphinx project.
In contrast to regular definition lists, multiple terms per entry are allowed, and inline markup is allowed in terms. You can link to all of the terms. For example:
.. glossary:: term 1 term 2 Definition of both terms.
(When the glossary is sorted, the first term determines the sort order.)
If you want to specify «grouping key» for general index entries, you can put a «key» as «term : key». For example:
.. glossary:: term 1 : A term 2 : B Definition of both terms.
Note that «key» is used for grouping key as is. The «key» isn’t normalized; key «A» and «a» become different groups. The whole characters in «key» is used instead of a first character; it is used for «Combining Character Sequence» and «Surrogate Pairs» grouping key.
In i18n situation, you can specify «localized term : key» even if original text only have «term» part. In this case, translated «localized term» will be categorized in «key» group.
Nuevo en la versión 0.6: You can now give the glossary directive a
:sorted:
flag that will automatically sort the entries alphabetically.Distinto en la versión 1.1: Now supports multiple terms and inline markup in terms.
Distinto en la versión 1.4: Index key for glossary term should be considered experimental.
Meta-information markup¶
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
show_authors
toTrue
to make them produce a paragraph in the output.
The
codeauthor
directive, which can appear multiple times, names the authors of the described code, just likesectionauthor
names the author(s) of a piece of documentation. It too only produces output if theshow_authors
configuration value isTrue
.
Index-generating markup¶
Sphinx automatically creates index entries from all object descriptions (like functions, classes or attributes) like discussed in Domains.
However, there is also explicit markup available, to make the index more comprehensive and enable index entries in documents where information is not mainly contained in information units, such as the language reference.
-
.. index::
<entries>
¶ This directive contains one or more index entries. Each entry consists of a type and a value, separated by a colon.
For example:
.. index:: single: execution; context module: __main__ module: sys triple: module; search; path The execution context --------------------- ...
This directive contains five entries, which will be converted to entries in the generated index which link to the exact location of the index statement (or, in case of offline media, the corresponding page number).
Since index directives generate cross-reference targets at their location in the source, it makes sense to put them before the thing they refer to – e.g. a heading, as in the example above.
The possible entry types are:
- single
- Creates a single index entry. Can be made a subentry by separating the subentry text with a semicolon (this notation is also used below to describe what entries are created).
- pair
pair: loop; statement
is a shortcut that creates two index entries, namelyloop; statement
andstatement; loop
.- triple
- Likewise,
triple: module; search; path
is a shortcut that creates three index entries, which aremodule; search path
,search; path, module
andpath; module search
. - see
see: entry; other
creates an index entry that refers fromentry
toother
.- seealso
- Like
see
, but inserts «see also» instead of «see». - module, keyword, operator, object, exception, statement, builtin
- These all create two index entries. For example,
module: hashlib
creates the entriesmodule; hashlib
andhashlib; module
. (These are Python-specific and therefore deprecated.)
You can mark up «main» index entries by prefixing them with an exclamation mark. The references to «main» entries are emphasized in the generated index. For example, if two pages contain
.. index:: Python
and one page contains
.. index:: ! Python
then the backlink to the latter page is emphasized among the three backlinks.
For index directives containing only «single» entries, there is a shorthand notation:
.. index:: BNF, grammar, syntax, notation
This creates four index entries.
Distinto en la versión 1.1: Added
see
andseealso
types, as well as marking main entries.
-
:index:
¶ While the
index
directive is a block-level markup and links to the beginning of the next paragraph, there is also a corresponding role that sets the link target directly where it is used.The content of the role can be a simple phrase, which is then kept in the text and used as an index entry. It can also be a combination of text and index entry, styled like with explicit targets of cross-references. In that case, the «target» part can be a full entry as described for the directive above. For example:
This is a normal reST :index:`paragraph` that contains several :index:`index entries <pair: index; entry>`.
Nuevo en la versión 1.1.
Including content based on tags¶
-
.. 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 withinconf.py
, see here) are true. Boolean expressions, also using parentheses (likehtml and (latex or draft)
) are supported.The format and the name of the current builder (
html
,latex
ortext
) are always set as a tag [4]. To make the distinction between format and name explicit, they are also added with the prefixformat_
andbuilder_
, e.g. the epub builder defines the tagshtml
,epub
,format_html
andbuilder_epub
.These standard tags are set after the configuration file is read, so they are not available there.
All tags must follow the standard Python identifier syntax as set out in the Identifiers and keywords documentation. That is, a tag expression may only consist of tags that conform to the syntax of Python variables. In ASCII, this consists of the uppercase and lowercase letters
A
throughZ
, the underscore_
and, except for the first character, the digits0
through9
.Nuevo en la versión 0.6.
Distinto en la versión 1.2: Added the name of the builder and the prefixes.
Advertencia
This directive is designed to control only content of document. It could not control sections, labels and so on.
Tables¶
Use reStructuredText tables, i.e. either
- grid table syntax (ref),
- simple table syntax (ref),
- csv-table syntax,
- or list-table syntax.
The table directive serves as optional wrapper of the grid and simple syntaxes.
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:
-
.. 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
flush left column with automatic width R
flush right column with automatic width C
centered column with automatic width J
justified column with automatic width The automatic widths of the
LRCJ
columns are attributed bytabulary
in proportion to the observed shares in a first pass where the table cells are rendered at their natural «horizontal» widths.By default, Sphinx uses a table layout with
J
for every column.Nuevo en la versión 0.3.
Distinto en la versión 1.6: Merged cells may now contain multiple paragraphs and are much better handled, thanks to custom Sphinx LaTeX macros. This novel situation motivated the switch to
J
specifier and notL
by default.Consejo
Sphinx actually uses
T
specifier having done\newcolumntype{T}{J}
. To revert to previous default, insert\newcolumntype{T}{L}
in the LaTeX preamble (seelatex_elements
).A frequent issue with tabulary is that columns with little contents are «squeezed». The minimal column width is a tabulary parameter called
\tymin
. You may set it globally in the LaTeX preamble via\setlength{\tymin}{40pt}
for example.Else, use the
tabularcolumns
directive with an explicitp{40pt}
(for example) for that column. You may use alsol
specifier but this makes the task of setting column widths more difficult if some merged cell intersects that column.Advertencia
Tables with more than 30 rows are rendered using
longtable
, nottabulary
, in order to allow pagebreaks. TheL
,R
, … specifiers do not work for these tables.Tables that contain list-like elements such as object descriptions, blockquotes or any kind of lists cannot be set out of the box with
tabulary
. They are therefore set with the standard LaTeXtabular
(orlongtable
) environment if you don’t give atabularcolumns
directive. If you do, the table will be set withtabulary
but you must use thep{width}
construct (or Sphinx’s\X
and\Y
specifiers described below) for the columns containing these elements.Literal blocks do not work with
tabulary
at all, so tables containing a literal block are always set withtabular
. The verbatim environment used for literal blocks only works inp{width}
(and\X
or\Y
) columns, hence Sphinx generates such column specs for tables containing literal blocks.Since Sphinx 1.5, the
\X{a}{b}
specifier is used (there is a backslash in the specifier letter). It is likep{width}
with the width set to a fractiona/b
of the current line width. You can use it in thetabularcolumns
(it is not a problem if some LaTeX macro is also called\X
.)It is not needed for
b
to be the total number of columns, nor for the sum of the fractions of the\X
specifiers to add up to one. For example|\X{2}{5}|\X{1}{5}|\X{1}{5}|
is legitimate and the table will occupy 80% of the line width, the first of its three columns having the same width as the sum of the next two.This is used by the
:widths:
option of the table directive.Since Sphinx 1.6, there is also the
\Y{f}
specifier which admits a decimal argument, such has\Y{0.15}
: this would have the same effect as\X{3}{20}
.Distinto en la versión 1.6: Merged cells from complex grid tables (either multi-row, multi-column, or both) now allow blockquotes, lists, literal blocks, … as do regular cells.
Sphinx’s merged cells interact well with
p{width}
,\X{a}{b}
,Y{f}
and tabulary’s columns.Nota
tabularcolumns
conflicts with:widths:
option of table directives. If both are specified,:widths:
option will be ignored.
Math¶
The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no further translation is necessary when building LaTeX output.
Keep in mind that when you put math markup in Python docstrings read by
autodoc
, you either have to double all backslashes,
or use Python raw strings (r"raw"
).
-
.. math::
¶ Directive for displayed math (math that takes the whole line for itself).
The directive supports multiple equations, which should be separated by a blank line:
.. math:: (a + b)^2 = a^2 + 2ab + b^2 (a - b)^2 = a^2 - 2ab + b^2
In addition, each single equation is set within a
split
environment, which means that you can have multiple aligned lines in an equation, aligned at&
and separated by\\
:.. math:: (a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2
For more details, look into the documentation of the AmSMath LaTeX package.
When the math is only one line of text, it can also be given as a directive argument:
.. math:: (a + b)^2 = a^2 + 2ab + b^2
Normally, equations are not numbered. If you want your equation to get a number, use the
label
option. When given, it selects an internal label for the equation, by which it can be cross-referenced, and causes an equation number to be issued. Seeeq
for an example. The numbering style depends on the output format.There is also an option
nowrap
that prevents any wrapping of the given math in a math environment. When you give this option, you must make sure yourself that the math is properly set up. For example:.. math:: :nowrap: \begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}
Ver también
- Math support for HTML outputs in Sphinx
- Rendering options for math with HTML builders.
latex_engine
- Explains how to configure LaTeX builder to support Unicode literals in math mark-up.
Grammar production displays¶
Special markup is available for displaying the productions of a formal grammar. The markup is simple and does not attempt to model all aspects of BNF (or any derived forms), but provides enough to allow context-free grammars to be displayed in a way that causes uses of a symbol to be rendered as hyperlinks to the definition of the symbol. There is this directive:
-
.. productionlist::
[name]
¶ This directive is used to enclose a group of productions. Each production is given on a single line and consists of a name, separated by a colon from the following definition. If the definition spans multiple lines, each continuation line must begin with a colon placed at the same column as in the first line.
The argument to
productionlist
serves to distinguish different sets of production lists that belong to different grammars.Blank lines are not allowed within
productionlist
directive arguments.The definition can contain token names which are marked as interpreted text (e.g.
sum ::= `integer` "+" `integer`
) – this generates cross-references to the productions of these tokens. Outside of the production list, you can reference to token productions usingtoken
.Note that no further reST parsing is done in the production, so that you don’t have to escape
*
or|
characters.
The following is an example taken from the Python Reference Manual:
.. productionlist::
try_stmt: try1_stmt | try2_stmt
try1_stmt: "try" ":" `suite`
: ("except" [`expression` ["," `target`]] ":" `suite`)+
: ["else" ":" `suite`]
: ["finally" ":" `suite`]
try2_stmt: "try" ":" `suite`
: "finally" ":" `suite`
Footnotes
[1] | The LaTeX writer only refers the maxdepth option of first toctree
directive in the document. |
[2] | A note on available globbing syntax: you can use the standard shell
constructs * , ? , [...] and [!...] with the feature that
these all don’t match slashes. A double star ** can be used to
match any sequence of characters including slashes. |
[3] | There is a standard .. include directive, but it raises errors if the
file is not found. This one only emits a warning. |
[4] | For most builders name and format are the same. At the moment only builders derived from the html builder distinguish between the builder format and the builder name. Note that the current builder tag is not available in |