Различная разметка

File-wide metadata

reST имеет концепцию “списка полей (field lists)”; это последовательность полей размеченных таким образом:

:fieldname: Содержимое поля

Список полей находящийся в начале файла рассматривается docutils как “docinfo (информация о документе)”, которая обычно используется для хранения информации об авторе, даты публикации и других метаданных. В Sphinx список полей, предшествующий любой другой разметке перемещается из docinfo в окружение Shpinx как метаданные документа и не отображается в выводе. Список же полей, расположенный после заголовка документа будет являться частью docinfo и будет отображён в выводе.

На данный момент распознаются следующие поля метаданных:

tocdepth

Максимальная глубина содержания в этом файле.

New in version 0.4.

nocomments

Если задано, то веб-приложение не будет отображать поле для комментариев для сгенерированной страницы из этого файла.

orphan

Если задано, то предупреждения о файлах, которые не включены ни в какое содержание будут подавляться.

New in version 1.0.

Разметка мета-информации

.. sectionauthor:: name <email>

Идентифицирует автора текущего раздела. Аргумент должен включать имя автора, которое может быть использовано для презентации и адрес электронной почты. Доменная часть адреса должна быть в нижнем регистре. Вот пример:

.. sectionauthor:: Guido van Rossum <guido@python.org>

По умолчанию, эта разметка никак не отображается в выводе (она помогает отслеживать вклады пользователей), но Вы можете установить в настроечном файле :confval:`show_authors` в True, чтобы эти данные выводились.

.. codeauthor:: name <email>

Директива codeauthor directive, which can appear multiple times, names the authors of the described code, just like sectionauthor names the author(s) of a piece of documentation. It too only produces output if the :confval:`show_authors` configuration value is True.

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, namely loop; statement and statement; loop.

triple

Likewise, triple: module; search; path is a shortcut that creates three index entries, which are module; search path, search; path, module and path; module search.

see

see: entry; other creates an index entry that refers from entry to other.

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 entries module; hashlib and hashlib; 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.

Changed in version 1.1: Added see and seealso 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>`.

New in version 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 within 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.

New in version 0.6.

Tables

Use standard reStructuredText 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:

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

New in version 0.3.

Warning

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 LaTeX tabular environment if you don’t give a tabularcolumns directive. If you do, the table will be set with tabulary, but you must use the p{width} construct for the columns that contain these elements.

Literal blocks do not work with tabulary at all, so tables containing a literal block are always set with tabular. 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 tabularcolumns directive to get finer control over such tables.