ディレクティブ

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.

参考

Refer to the reStructuredText Primer for an overview of the directives provided by Docutils.

Table of contents

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

注釈

単純に一つのファイルを別のファイルに"挿入"する場合、 include ディレクティブを使えます。

注釈

To create table of contents for current document (.rst file), use the standard reStructuredText contents directive.

.. toctree::

このディレクティブは"目次のツリー"を現在の場所に挿入します。目次の生成には、ディレクティブ本体で指定された関連ドキュメントの中の個別の目次("サブ目次ツリー"も含む)も使用されます。(/ で始まらない)相対的なドキュメント名が指定された場合は現在のドキュメントからの相対パスとして、絶対的なドキュメント名が指定された場合はソースディレクトリからの相対パスとして、それぞれ取り扱われます。 maxdepth オプションの数値を設定すると、ツリーの深さを設定できます。デフォルトではすべての階層を含むツリーが作成されます。 [1]

The representation of "TOC tree" is changed in each output format. The builders that output multiple files (e.g. HTML) treat it as a collection of hyperlinks. On the other hand, the builders that output a single file (e.g. LaTeX, man page, etc.) replace it with the content of the documents on the TOC tree.

このサンプルを見てください。このサンプルはPythonドキュメントのライブラリリファレンスからの引用です:

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

このディレクティブは二つのことを行っています。

  • ここで指定されたファイル群(intro, stringsなど)の項目も取り込んで目次を作成しています。最大の深さは2に指定されています。つまり、関連するドキュメントからトップの1階層分の項目を取得してきて目次に挿入しています。指定されたファイルに toctree ディレクティブがあればそれも利用されます。

  • Sphinxはこのディレクティブから、関連するドキュメントが intro, strings という順番を持っていて、これらのファイルがライブラリインデックスの子供であるという情報を収集します。これらの情報を使って、"next chapter", "previous chapter", "parent chapter"というリンクが作成されます。

エントリー

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 reStructuredText hyperlinks (and Sphinx's cross-referencing syntax). This looks like:

.. toctree::

   intro
   All about strings <strings>
   datatypes

上記のサンプルの2行目は strings ドキュメントへのリンクになります。デフォルトの動作では strings ドキュメントのタイトルが使用されますが、ここでは"文字列のすべて"という文字列がタイトルとして使用されます。

また、ドキュメント名の代わりに、HTTPのURLを指定することで外部へのリンクも追加できます。

self は特別なエントリー名として扱われます。toctreeディレクティブを含むドキュメント自身を表します。これは、toctreeを使用して、"サイトマップ"を作成したい場合に便利です。

最後になりますが ソースディレクトリ (サブディレクトリも含む)の中のドキュメントは、いずれかの toctree ディレクティブの中にリストアップされなければいけません。ソースフォルダには置いてあるが、リストアップされていないファイルがあると、通常のナビゲーションではそのファイルに到達できないということになるため、Sphinxは警告を出力します。

exclude_patterns を使って明示することで、ビルド対象からドキュメントを外すこともできます。ドキュメントをビルドさせる場合には the "orphan" metadata を使用して下さい、toctreeを通じて到達できないことをSphinxへ知らせます。

The "root document" (selected by root_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 a :maxdepth: option.

バージョン 0.6 で変更: Added support for external links and "self" references.

オプション

:class: class names (a list of class names, separated by spaces)

Assign class attributes. This is a common option. For example:

.. toctree::
   :class: custom-toc

Added in version 7.4.

:name: label (text)

An implicit target name that can be referenced using ref. This is a common option. For example:

.. toctree::
   :name: mastertoc

   foo

Added in version 1.3.

:caption: (text)

Add a caption to the toctree. For example:

.. toctree::
   :caption: Table of Contents

    foo

Added in version 1.3.

:numbered:
:numbered: depth

If you want to have section numbers even in HTML output, add the :numbered: option to the top-level toctree. For example:

.. toctree::
   :numbered:

   foo
   bar

Section numbering then starts at the heading of foo. Sub-toctrees are automatically numbered (don't give the numbered flag to those).

特定の深さまでのナンバリングだけを行うこともできます。 numbered オプションに対して、数値で深さを指定してください。

Added in version 0.6.

バージョン 1.1 で変更: Added the numeric depth argument.

:titlesonly:

Only list document titles, not other headings of the same level. For example:

.. toctree::
   :titlesonly:

   foo
   bar

Added in version 1.0.

:glob:

Parse glob wildcards in toctree entries. All entries are matched against the list of available documents, and matches are inserted into the list alphabetically. For example:

.. toctree::
   :glob:

   intro*
   recipe/*
   *

このディレクティブの先頭では、名前が intro で始まるすべてのドキュメントが挿入されます。その次には、 recipe フォルダの中の全てのドキュメントが挿入されます。最後に、一度も挿入されていない、残ったドキュメントが挿入されます。 [2]

Added in version 0.3.

:reversed:

Reverse the order of the entries in the list. This is particularly useful when using the :glob: option.

Added in version 1.5.

:hidden:

A hidden toctree only defines the document hierarchy. It will not insert links into the document at the location of the directive.

This makes sense if you have other means of navigation, e.g. through manual links, HTML sidebar navigation, or if you use the :includehidden: option on the top-level toctree.

Added in version 0.6.

:includehidden:

If you want one global table of contents showing the complete document structure, you can add the :includehidden: option to the top-level toctree directive. All other toctrees on child pages can then be made invisible with the :hidden: option. The top-level toctree with :includehidden: will then include their entries.

Added in version 1.2.

特別なドキュメント名

Sphinxはいくつかのドキュメント名を、自分で使用するために予約済みとしています。これらの名前を持つドキュメントを作ろうとしてはいけません。問題が発生することになります。

以下の名前(もしくはこれらから作られるページ名)が特別なドキュメント名です:

  • genindex

    This is used for the general index, which is populated with entries from index directives and all index-generating object descriptions. For example, see Sphinx's 索引.

  • modindex

    This is used for the Python module index, which contains one entry per py:module directive. For example, see Sphinx's Pythonモジュール索引.

  • search

    This is used for the search page, which contains a form that uses the generated JSON search index and JavaScript to full-text search the generated documents for search words; it works on every major browser. For example, see Sphinx's 検索ページ.

  • Every name beginning with _

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

警告

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.

パラグラフ階層のマークアップ

These directives create short paragraphs and can be used inside information units as well as normal text.

Admonitions, messages, and warnings

The admonition directives create 'admonition' elements, a standardised system of communicating different types of information, from a helpful tip to matters of paramount danger. These directives can be used anywhere an ordinary body element can, and can contain arbitrary body elements. There are nine specific named admonitions and the generic admonition directive.

.. attention::

Information that requires the reader's attention. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

注意

Please may I have your attention.

.. caution::

Information with regard to which the reader should exercise care. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

注意

Exercise due caution.

.. danger::

Information which may lead to near and present danger if not heeded. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

危険

Let none think to fly the danger for soon or late love is his own avenger.

.. error::

Information relating to failure modes of some description. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

エラー

ERROR 418: I'm a teapot.

.. hint::

Information that is helpful to the reader. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

ヒント

Look under the flowerpot.

.. important::

Information that is of paramount importance and which the reader must not ignore. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

重要

This is a statement of paramount importance.

.. note::

An especially important bit of information that the reader should know. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

注釈

This function is not suitable for sending tins of spam.

.. tip::

Some useful tidbit of information for the reader. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

Tip

Remember your sun cream!

.. warning::

An important bit of information that the reader should be very aware of. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

警告

Beware of the dog.

.. admonition:: title

A generic admonition, with an optional title. The content of the directive should be written in complete sentences and include all appropriate punctuation.

例:

This is a title

This is the content of the admonition.

.. 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. The content of the seealso directive should be either a single line or a reStructuredText definition list.

サンプル:

.. seealso::

   Python's :py:mod:`zipfile` module
      Documentation of Python's standard :py:mod:`zipfile` module.

   `GNU tar manual, Basic Tar Format <https://example.org>`_
      Documentation for tar archive files, including GNU tar extensions.

参考

Module zipfile

Documentation of the zipfile standard module.

GNU tar manual, Basic Tar Format

Documentation for tar archive files, including GNU tar extensions.

Describing changes between versions

.. versionadded:: version [brief explanation]

This directive documents the version of the project which added the described feature. When this applies to an entire module or component, it should be placed at the top of the relevant section before any prose.

最初の引数は必須で、バージョン番号を書く必要があります。2番目の引数も追加でき、変化に対する 短い 説明を書くことができます。

注意

There must be no blank line between the directive head and the explanation; this is to make these blocks visually continuous in the markup.

サンプル:

.. versionadded:: 2.5
   The *spam* parameter.

Added in version 2.5: The spam parameter.

.. versionchanged:: version [brief explanation]

versionadded と似ていますが、現在説明している機能がいつどのように変化したのか(新しい引数、副作用の変更など)を説明するのに使用します。

サンプル:

.. versionchanged:: 2.8
   The *spam* parameter is now of type *boson*.

バージョン 2.8 で変更: The spam parameter is now of type boson.

.. deprecated:: version [brief explanation]

Similar to versionadded, but describes when the feature was deprecated. A brief explanation can also be given, for example to tell the reader what to use instead.

サンプル:

.. deprecated:: 3.1
   Use :py:func:`spam` instead.

バージョン 3.1 で非推奨: Use spam() instead.

.. versionremoved:: version [brief explanation]

Similar to versionadded, but describes when the feature was removed. An explanation may be provided to tell the reader what to use instead, or why the feature was removed.

Added in version 7.3.

サンプル:

.. versionremoved:: 4.0
   The :py:func:`spam` function is more flexible, and should be used instead.

Removed in version 4.0: The spam() function is more flexible, and should be used instead.

Presentational

.. rubric:: title

A rubric is like an informal heading that doesn't correspond to the document's structure, i.e. it does not create a table of contents node.

注釈

もし rubricディレクティブの タイトル が"Footnotes"(もしくは選択された言語で指定されている、同様の言葉)だった場合には、脚注の定義だけが含まれていると見なして、LaTeXライターでは無視されます。この場合は空の見出しだけが作成されます。

オプション

:class: class names (a list of class names, separated by spaces)

Assign class attributes. This is a common option.

:name: label (text)

An implicit target name that can be referenced using ref. This is a common option.

:heading-level: n (number from 1 to 6)

Added in version 7.4.1.

Use this option to specify the heading level of the rubric. In this case the rubric will be rendered as <h1> to <h6> for HTML output, or as the corresponding non-numbered sectioning command for LaTeX (see latex_toplevel_sectioning).

.. centered::

This directive creates a centered boldfaced line of text.

バージョン 1.1 で非推奨: This presentation-only directive is a legacy from older versions. Use a rst-class directive instead and add an appropriate style.

.. hlist::

このディレクティブは短い文章のリストを含みます。このディレクティブは、水平にも数カラム展開することで、よりコンパクトなリストに変換するか、アイテム間のスペースを小さくします。どちらになるかはビルダー次第です。

オプション

:columns: n (int)

The number of columns; defaults to 2. For example:

.. hlist::
   :columns: 3

   * A list of
   * short items
   * that should be
   * displayed
   * horizontally

Added in version 0.6.

コードサンプルの表示

There are multiple ways to show syntax-highlighted literal code blocks in Sphinx:

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 (ハイライトしない)

  • default (similar to python3 but with a fallback to none without warning highlighting fails; the default when highlight_language isn't set)

  • guess (Pygmentsに推測させます。推測しやすい言語でないとうまく動作しません)

  • python

  • rest

  • c

  • ... and any other lexer alias that Pygments supports

選択された言語によるハイライトがうまくいかなかった場合(例えば、Pygmentsが"Error"トークンを出す等)には、そのブロックはハイライトされなくなります。

重要

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

サンプル:

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

オプション

:linenothreshold: threshold (number (optional))

Enable to generate line numbers for code blocks.

This option takes an optional number as threshold parameter. If any threshold given, the directive will produce line numbers only for the code blocks longer than N lines. If not given, line numbers will be produced for all of code blocks.

サンプル:

.. highlight:: python
   :linenothreshold: 5
:force: (no value)

If given, minor errors on highlighting are ignored.

Added in version 2.1.

.. code-block:: [language]
.. sourcecode:: [language]
.. code:: [language]

サンプル:

.. code-block:: ruby

   Some Ruby code.

The directive's alias name sourcecode works as well. This directive takes a language name as an argument. It can be any lexer alias supported by Pygments. If it is not given, the setting of highlight directive will be used. If not set, highlight_language will be used. To display a code example inline within other text, rather than as a separate block, you can use the code role instead.

バージョン 2.0 で変更: The language argument becomes optional.

オプション

:linenos: (no value)

Enable to generate line numbers for the code block:

.. code-block:: ruby
   :linenos:

   Some more Ruby code.
:lineno-start: number (number)

Set the first line number of the code block. If present, linenos option is also automatically activated:

.. code-block:: ruby
   :lineno-start: 10

   Some more Ruby code, with line numbering starting at 10.

Added in version 1.3.

:emphasize-lines: line numbers (comma separated numbers)

Emphasize particular lines of the code block:

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

Added in version 1.1.

バージョン 1.6.6 で変更: LaTeX が emphasize-lines オプションをサポートしました。

:force: (no value)

Ignore minor errors on highlighting.

Added in version 2.1.

:caption: caption of code block (text)

Set a caption to the code block.

Added in version 1.3.

:name: a label for hyperlink (text)

Define implicit target name that can be referenced by using ref. For example:

.. code-block:: python
   :caption: this.py
   :name: this-py

   print('Explicit is better than implicit.')

In order to cross-reference a code-block using either the ref or the numref role, it is necessary that both name and caption be defined. The argument of name can then be given to numref to generate the cross-reference. Example:

See :numref:`this-py` for an example.

When using ref, it is possible to generate a cross-reference with only name defined, provided an explicit title is given. Example:

See :ref:`this code snippet <this-py>` for an example.

Added in version 1.3.

:class: class names (a list of class names separated by spaces)

Assign class attributes. This is a common option.

Added in version 1.4.

:dedent: number (number or no value)

Strip indentation characters from the code block. When number given, leading N characters are removed. When no argument given, leading spaces are removed via textwrap.dedent(). For example:

.. code-block:: ruby
   :linenos:
   :dedent: 4

       some ruby code

Added in version 1.3.

バージョン 3.5 で変更: Support automatic dedent.

.. 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 file example.py, use:

.. literalinclude:: example.py

ソースコードのファイルは通常、現在のパスからの相対パスで指定します。 / から開始されているときはトップのソースディレクトリからのパス指定をできます。

General options

:class: class names (a list of class names, separated by spaces)

Assign class attributes. This is a common option.

Added in version 1.4.

:name: label (text)

An implicit target name that can be referenced using ref. This is a common option.

Added in version 1.3.

:caption: caption (text)

Add a caption above the included content. If no argument is given, the filename is used as the caption.

Added in version 1.3.

Options for formatting

:dedent: number (number or no value)

Strip indentation characters from the included content. When a number is given, the leading N characters are removed. When no argument given, all common leading indentation is removed (using textwrap.dedent()).

Added in version 1.3.

バージョン 3.5 で変更: Support automatic dedent.

:tab-width: N (number)

Expand tabs to N spaces.

Added in version 1.0.

:encoding: (text)

Explicitly specify the encoding of the file. This overwrites the default encoding (source_encoding). For example:

.. literalinclude:: example.txt
   :encoding: latin-1

Added in version 0.4.3.

:linenos: (no value)

Show line numbers alongside the included content. By default, line numbers are counted from 1. This can be changed by the options :lineno-start: and :lineno-match:.

:lineno-start: number (number)

Set line number for the first line to show. If given, this automatically activates :linenos:.

:lineno-match:

When including only parts of a file and show the original line numbers. This is only allowed only when the selection consists of contiguous lines.

Added in version 1.3.

:emphasize-lines: line numbers (comma separated numbers)

Emphasise particular lines of the included content. For example:

.. literalinclude:: example.txt
   :emphasize-lines: 1,2,4-6
:language: language (text)

Select a highlighting language (Pygments lexer) different from the current file's standard language (set by highlight or highlight_language).

:force: (no value)

Ignore minor errors in highlighting.

Added in version 2.1.

Options for selecting the content to include

:pyobject: object (text)

For Python files, only include the specified class, function or method:

.. literalinclude:: example.py
   :pyobject: Timer.start

Added in version 0.6.

:lines: line numbers (comma separated numbers)

Specify exactly which lines to include:

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

This includes line 1, line 3, lines 5 to 10, and line 20 to the end.

Added in version 0.6.

:start-at: text
:start-after: text
:end-before: text
:end-at: text

Another way to control which part of the file is included is to use the start-after and end-before options (or only one of them). If start-after is given as a string option, only lines that follow the first line containing that string are included. If end-before is given as a string option, only lines that precede the first lines containing that string are included. The start-at and end-at options behave in a similar way, but the lines containing the matched string are included.

start-after/start-at and end-before/end-at can have same string. start-after/start-at filter lines before the line that contains the option string (start-at will keep the line). Then end-before/end-at filter lines after the line that contains the option string (end-at will keep the line and end-before skip the first line).

Added in version 0.6: Added the start-after and end-before options.

Added in version 1.5: Added the start-at, and end-at options.

Tip

To only select [second-section] of an INI file such as the following, use :start-at: [second-section] and :end-before: [third-section]:

[first-section]
var_in_first=true

[second-section]
var_in_second=true

[third-section]
var_in_third=true

These options can be useful when working with tag comments. Using :start-after: [initialise] and :end-before: [initialised] keeps the lines between between the two comments below:

if __name__ == "__main__":
    # [initialise]
    app.start(":8000")
    # [initialised]

When lines have been selected in any of the ways described above, the line numbers in emphasize-lines refer to these selected lines, counted consecutively starting from 1.

:prepend: line (text)

Prepend a line before the included code. This can be useful for example when highlighting PHP code that doesn't include the <?php or ?> markers.

Added in version 1.0.

:append: line (text)

Append a line after the included code. This can be useful for example when highlighting PHP code that doesn't include the <?php or ?> markers.

Added in version 1.0.

:diff: filename

Show the diff of two files. For example:

.. literalinclude:: example.txt
   :diff: example.txt.orig

This shows the diff between example.txt and example.txt.orig with unified diff format.

Added in version 1.3.

バージョン 0.6 で変更: Added support for absolute filenames.

バージョン 1.6 で変更: start-after と lines の両方を使っているときは、 start-after を基準とした先頭行が lines における行番号 1 となります。

用語集

.. glossary::

This directive must contain a reStructuredText 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.

通常の定義リストとは異なり、一つのエントリーに対して、複数の 用語を定義できます。それぞれの用語に対してインラインマークアップを使えます。また、すべての用語への参照も可能です:

.. glossary::

   term 1
   term 2
      Definition of both terms.

(用語集がソートされる場合、最初の項がソート順序を決定します。)

一般的な索引項目に "グループ化キー" を指定する場合は、 "キー" を "term : key" とします。例えば:

.. glossary::

   term 1 : A
   term 2 : B
      Definition of both terms.

キーをそのままグループ化する場合は、 "key" を使用します。 "key" は正規化されません。key "A" とkey "a" は異なるグループになります。 "key" 内のすべての文字が最初の文字の代わりに使用されます。 "文字シーケンスの結合" と "代理ペア" のグルーピングキーに使用します。

i18nの場合、原文が "term" のみの場合でも "localized term : key" を指定できますが、この場合、翻訳された "localized term" は "key" グループに分類されます。

バージョン 1.1 で変更: 複数の用語をサポートし、また、用語の中でインラインマークアップを使えるようになりました。

バージョン 1.4 で変更: Index key for glossary term should be considered experimental.

オプション

:sorted:

Sort the entries alphabetically.

Added in version 0.6.

バージョン 4.4 で変更: In internationalized documentation, sort according to translated terms.

メタ情報マークアップ

.. sectionauthor:: name <email>

現在のセクションの著者名を指定します。引数には必ず、表示するための著者の名前と、電子メールのアドレスを入れます。アドレスのドメイン名の部分は小文字でなければなりません。 サンプル:

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

デフォルトでは、このマークアップは出力に反映されません(貢献者の名前を調べる手助けにはなります)。しかし、設定ファイルの show_authors を True に設定すると、出力ファイルの中にこの情報に関する段落が作成されます。

.. codeauthor:: name <email>

codeauthor ディレクティブは、 sectionauthor の名前と同じく、説明しているコードの作者名について、複数人書くことができます。 show_authors 設定値を True にしないかぎり、出力はされません。

インデックス生成のためのマークアップ

Sphinx automatically creates index entries from all object descriptions (like functions, classes or attributes) like discussed in Domains.

しかし、これ以外に明示的に指定するディレクティブもあります。これを使用することで、言語のリファレンスのように、メインの情報のユニットが存在しない情報をドキュメントの中に書いてインデックスのエントリーを作ることができるようになります。より包括的なインデックスを作成できるようになります。

.. index:: <entries>

このディレクティブは一つ以上のインデックスのエントリーを含みます。それぞれのエントリーはコロン(:)で区切られた、タイプ、値を含みます。

例えば:

.. index::
   single: execution; context
   pair: module; __main__
   pair: module; sys
   triple: module; search; path
   seealso: scope

The execution context
---------------------

...

このディレクティブは5つのエントリーを含んでいます。これらは生成されたインデックスのエントリーに変換され、index文の正確な位置へのリンクが張られることになります。オフラインのメディアに出力される場合には、リンクの代わりに対応するページ番号が出力されます。

indexディレクティブはそのソースの位置のターゲットとのクロスリファレンスを生成するため、それらが参照するものの 前の位置 に置くことが大切になります。上記のサンプルコードの例では、リンクを張りたい見出しの前に配置されています。

設定可能なエントリーのタイプは以下の通りです:

single

Creates a single index entry. Can be made a sub-entry by separating the sub-entry text with a semicolon (this notation is also used below to describe what entries are created). Examples:

.. index:: single: execution
           single: execution; context

  • single: execution creates an index entry labelled execution.

  • single: execution; context creates an sub-entry of execution labelled context.

pair

A shortcut to create two index entries. The pair of values must be separated by a semicolon. Example:

.. index:: pair: loop; statement

This would create two index entries; loop; statement and statement; loop.

triple

A shortcut to create three index entries. All three values must be separated by a semicolon. Example:

.. index:: triple: module; search; path

This would create three index entries; module; search path, search; path, module, and path; module search.

see

A shortcut to create an index entry that refers to another entry. Example:

.. index:: see: entry; other

This would create an index entry referring from entry to other (i.e. 'entry': See 'other').

seealso

see と似ていますが、 'see' の代わりに、 'see also' を挿入します。

module, keyword, operator, object, exception, statement, builtin

These deprecated shortcuts all create two index entries. For example, module: hashlib creates the entries module; hashlib and hashlib; module.

バージョン 1.0 で非推奨: These Python-specific entry types are deprecated.

バージョン 7.1 で変更: Removal version set to Sphinx 9.0. Using these entry types will now emit warnings with the index category.

もしエクスクラメーションマーク(!)を前に付けると、主要なインデックスエントリーである、ということを表現できます。主要なインデックスは、生成されたインデックスの中で強調されます。例えば、2つのページが次のようなディレクティブを持っていたとします:

.. index:: Python

そして、次の内容を含むページがあったとします:

.. index:: ! Python

この場合、最後のページへのバックリンクが3つの中では強調されて表示されます。

"single"のエントリーだけが含まれるindexディレクティブの場合、以下のように短縮記法で簡単に作成することもできます:

.. index:: BNF, grammar, syntax, notation

これは4つのインデックスのエントリーが作成されます。

バージョン 1.1 で変更: see と seealso を追加しました。

オプション

:name: a label for hyperlink (text)

Define implicit target name that can be referenced by using ref. For example:

.. index:: Python
   :name: py-index

Added in version 3.0.

:index:

index ディレクティブは、ブロックレベルのマークアップで、次のパラグラフの先頭に対するリンクを生成します。これとは別に、直接リンクターゲットに設定するロールもあります。

ロールのコンテンツは、文章の中にあるシンプルなフレーズで、そのままインデックスのエントリーとして使用されます。テキストと入力エントリーの組み合わせになっていて、明示的なクロスリファレンスのターゲットになります。この場合、ターゲットの部分は上記で説明したディレクティブの機能をフルに使うことができます:

This is a normal reStructuredText :index:`paragraph` that contains several
:index:`index entries <pair: index; entry>`.

Added in version 1.1.

タグを使用したインクルード

.. only:: <expression>

条件式(expression) が真のときだけ、ディレクティブの内容をインクルードします。条件式は以下のようにタグで構成されます。

.. only:: html and draft

Undefined tags are false, defined tags are true (tags can be defined via the --tag command-line option or within conf.py, see here). Boolean expressions (like (latex or html) and draft) are supported and may use parentheses.

現在のビルダー (html 、 latex 、 text) の フォーマット と 名前 が常にタグ [4] として設定されます。フォーマットと名前とを明示的に区別するために、 format_ と builder_ というプレフィックスも追加されました。 例: epubビルダーは html 、 epub 、 format_html 、 builder_epub の４つのタグが定義されます。

これらの標準タグは、conf.pyを読み込んだ 後 に設定されるため、conf.pyではこれらのタグの有無を参照できません。

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 through Z, the underscore _ and, except for the first character, the digits 0 through 9.

Added in version 0.6.

バージョン 1.2 で変更: builder名とプレフィックスが追加されました。

警告

このディレクティブはドキュメントの文面を制御するようにデザインされています。セクションやラベルは制御できません。

テーブル

Use reStructuredText tables, i.e. either

The table directive serves as optional wrapper of the grid and simple syntaxes.

They work fine in HTML output, but rendering tables to LaTeX is complex. Check the latex_table_style.

バージョン 1.6 で変更: Merged cells (multi-row, multi-column, both) from grid tables containing complex contents such as multiple paragraphs, blockquotes, lists, literal blocks, will render correctly to LaTeX output.

.. tabularcolumns:: column spec

This directive influences only the LaTeX output for the next table in source. The mandatory argument is a column specification (known as an "alignment preamble" in LaTeX idiom). Please refer to a LaTeX documentation, such as the wiki page, for basics of such a column specification.

Added in version 0.3.

注釈

tabularcolumns conflicts with :widths: option of table directives. If both are specified, :widths: option will be ignored.

Sphinx will render tables with more than 30 rows with longtable. Besides the l, r, c and p{width} column specifiers, one can also use \X{a}{b} (new in version 1.5) which configures the column width to be a fraction a/b of the total line width and \Y{f} (new in version 1.6) where f is a decimal: for example \Y{0.2} means that the column will occupy 0.2 times the line width.

When this directive is used for a table with at most 30 rows, Sphinx will render it with tabulary. One can then use specific column types L (left), R (right), C (centered) and J (justified). They have the effect of a p{width} (i.e. each cell is a LaTeX \parbox) with the specified internal text alignment and an automatically computed width.

警告

  • Cells that contain list-like elements such as object descriptions, blockquotes or any kind of lists are not compatible with the LRCJ column types. The column type must then be some p{width} with an explicit width (or \X{a}{b} or \Y{f}).

  • Literal blocks do not work with tabulary at all. Sphinx will fall back to tabular or longtable environments and generate a suitable column specification.

In absence of the tabularcolumns directive, and for a table with at most 30 rows and no problematic cells as described in the above warning, Sphinx uses tabulary and the J column-type for every column.

バージョン 1.6 で変更: Formerly, the L column-type was used (text is flushed-left). To revert to this, include \newcolumntype{T}{L} in the LaTeX preamble, as in fact Sphinx uses T and sets it by default to be an alias of J.

ヒント

A frequent issue with tabulary is that columns with little contents appear to be "squeezed". One can add to the LaTeX preamble for example \setlength{\tymin}{40pt} to ensure a minimal column width of 40pt, the tabulary default of 10pt being too small.

ヒント

To force usage of the LaTeX longtable environment pass longtable as a :class: option to table, csv-table, or list-table. Use rst-class for other tables.

Math

数式の入力言語としてはLaTeXのマークアップを利用します。これはプレーンテキストで数式を表現する記法としてはデファクトスタンダードになっています。また、LaTeX出力を行う場合には、変換をしないでそのまま利用できるというメリットもあります。

autodoc で読み込まれた Python docstrings の中に数式を入れるときには、すべてのバックスラッシュを二重にするか、Pythonのraw strings (r"raw") を使う必要があることに注意してください。

.. math::

数式を表示するディレクティブです。この数式は１行丸ごと使って表示されます。

このディレクティブは、複数行の等式をサポートしています。複数行に記述したい場合には、空行で区切ります:

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

それぞれの数式は 分割された 環境にセットされます。もしも、複数行の等式をきれいに整列させたい場合には、 \\ で区切って、 & 記号を使って整列させます:

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

もっと詳しく知りたい場合には AmSMath LaTeX パッケージ のドキュメントを参照してください。

数式が一行のテキストに収まる場合には、ディレクティブの引数として記述もできます:

.. math:: (a + b)^2 = a^2 + 2ab + b^2

オプション

:class: class names (a list of class names, separated by spaces)

Assign class attributes. This is a common option.

:name: label (text)

An implicit target name that can be referenced using ref. This is a common option.

:label: label (text)

通常、数式には番号が付きません。数式に番号をつけたい場合は、 label オプションを使用してください。これが指定されると、数式のラベルを選択できます。この数式のラベルを使ってクロスリファレンスを作成することができます。例は eq を参照してください。ナンバリングの形式は出力フォーマットに依存します。

:nowrap:

Prevent 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}

参考

SphinxにおけるHTML出力での数式サポート

Rendering options for math with HTML builders.

latex_engine

Explains how to configure LaTeX builder to support Unicode literals in math mark-up.

文法規則表示

形式がきちんとした文法の規則を表示するための特別なマークアップを利用できます。マークアップはシンプルに作られています。その代わりに、BNFや、BNFの派生の記法をすべてのモデル化することは目標とされていませんが、文脈自由文法を表現するには十分な機能を持っていて、シンボルを書くと、定義にリンクが張られるようにレンダリングされます。以下のディレクティブがあります:

.. productionlist:: [productionGroup]

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

The productionGroup argument to productionlist serves to distinguish different sets of production lists that belong to different grammars. Multiple production lists with the same productionGroup thus define rules in the same scope.

Inside of the production list, tokens implicitly refer to productions from the current group. You can refer to the production of another grammar by prefixing the token with its group name and a colon, e.g, "otherGroup:sum". If the group of the token should not be shown in the production, it can be prefixed by a tilde, e.g., "~otherGroup:sum". To refer to a production from an unnamed grammar, the token should be prefixed by a colon, e.g., ":sum".

Outside of the production list, if you have given a productionGroup argument you must prefix the token name in the cross-reference with the group name and a colon, e.g., "myGroup:sum" instead of just "sum". If the group should not be shown in the title of the link either an explicit title can be given (e.g., "myTitle <myGroup:sum>"), or the target can be prefixed with a tilde (e.g., "~myGroup:sum").

Note that no further reStructuredText parsing is done in the production, so that you don't have to escape * or | characters.

次のサンプルは、Pythonのリファレンスマニュアルにあった構文をSphinxで表現したものです:

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

脚注