ディレクティブ

前述のように、ディレクティブは明示的なマークアップの汎用的なブロックです。Docutils は多くのディレクティブを提供していますが、Sphinx はさらに多くのディレクティブを提供し、主要な拡張メカニズムの1つとしてディレクティブを使用しています。

ドメインによって追加されたロールについては、そちらを参照してください。

こちらも参照

Docutils が提供するディレクティブの概要については、reStructuredText入門を参照してください。

目次

reStructuredText は複数のドキュメントを相互に接続したり、ドキュメントを複数の出力ファイルに分割したりする機能を持っていないため、Sphinx はドキュメントが構成される個々のファイル間の関係と目次を追加するためにカスタムディレクティブを使用します。toctree ディレクティブが中心的な要素です。

注意

あるファイルから別のファイルを単純に「インクルード」するには、include ディレクティブを使用できます。

注意

現在のドキュメント（.rst ファイル）の目次を作成するには、標準的な reStructuredText のcontents ディレクティブを使用します。

.. toctree::

このディレクティブは、ディレクティブ本文に指定されたドキュメントの個々の目次（「サブ目次ツリー」を含む）を使用して、「目次ツリー」を現在の場所に挿入します。スラッシュで始まらない相対的なドキュメント名は、ディレクティブが存在するドキュメントを基準とした相対名であり、絶対名はソースディレクトリを基準とした絶対名です。ツリーの深さを示す数値のmaxdepthオプションを指定できます。デフォルトでは、すべてのレベルが含まれます。[1]

「目次ツリー」の表現は、各出力形式で変更されます。複数のファイルを出力するビルダー（例：HTML）は、それをハイパーリンクの集合として扱います。一方、単一のファイルを出力するビルダー（例：LaTeX、man ページなど）は、それを目次ツリー上のドキュメントの内容に置き換えます。

この例を考えてみましょう（Python ドキュメントのライブラリ参照インデックスからの抜粋です）

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

これにより、2つのことが達成されます。

  • これらのドキュメントのすべての目次が、最大深さ2、つまりネストされた見出しが1つ挿入されます。toctree ディレクティブも考慮されます。

  • Sphinx はドキュメントintro、stringsなどの相対的な順序を知っており、それらが表示されているドキュメント（ライブラリインデックス）の子であることを知っています。この情報から、「次の章」、「前の章」、「親の章」へのリンクを生成します。

エントリ

toctree内のドキュメントタイトルは、参照されているドキュメントのタイトルから自動的に読み取られます。それが望ましいものでない場合は、reStructuredText のハイパーリンク（および Sphinx の相互参照構文）と同様の構文を使用して、明示的なタイトルとターゲットを指定できます。これは次のようになります。

.. toctree::

   intro
   All about strings <strings>
   datatypes

上記の2行目はstringsドキュメントへのリンクになりますが、stringsドキュメントのタイトルではなく、「文字列についてすべて」というタイトルが使用されます。

ドキュメント名ではなく HTTP URL を指定することで、外部リンクを追加することもできます。

特別なエントリ名selfは、toctree ディレクティブを含むドキュメントを表します。これは、toctree から「サイトマップ」を生成する場合に役立ちます。

最終的に、ソースディレクトリ（またはサブディレクトリ）内のすべてのドキュメントは、いくつかのtoctree ディレクティブに存在する必要があります。含まれていないファイルが見つかった場合、Sphinx は警告を出力します。これは、そのファイルが標準的なナビゲーションを通じてアクセスできないことを意味するためです。

ドキュメントまたはディレクトリを完全にビルドから除外するには、exclude_patternsを使用します。「orphan」メタデータを使用して、ドキュメントをビルドできるようにしながら、toctree を介してアクセスできないことを Sphinx に通知します。

「ルートドキュメント」（root_docで選択）は、目次ツリー階層の「ルート」です。:maxdepth:オプションを指定しない場合、ドキュメントのメインページとして、または「完全な目次」として使用できます。

バージョン 0.6 で変更されました: 外部リンクと「self」参照のサポートが追加されました。

オプション

:class: クラス名 (スペースで区切られたクラス名のリスト)

クラス属性を割り当てます。これは一般的なオプションです。たとえば

.. toctree::
   :class: custom-toc

バージョン 7.4 で追加されました。

:name: ラベル (テキスト)

refを使用して参照できる暗黙的なターゲット名です。これは一般的なオプションです。たとえば

.. toctree::
   :name: mastertoc

   foo

バージョン 1.3 で追加されました。

:caption: (テキスト)

toctree にキャプションを追加します。たとえば

.. toctree::
   :caption: Table of Contents

    foo

バージョン 1.3 で追加されました。

:numbered:
:numbered: depth

HTML出力でセクション番号を付けるには、最上位のtoctreeに:numbered:オプションを追加します。例:

.. toctree::
   :numbered:

   foo
   bar

セクション番号付けはfooの見出しから始まります。サブtoctreeは自動的に番号付けされます（サブtoctreeにはnumberedフラグを付けないでください）。

numberedに数値引数として深度を指定することで、特定の深度までの番号付けも可能です。

バージョン0.6で追加されました。

バージョン1.1で変更されました: 数値のdepth引数を追加しました。

:titlesonly:

ドキュメントのタイトルのみをリストし、同じレベルの他の見出しはリストしません。例:

.. toctree::
   :titlesonly:

   foo
   bar

バージョン1.0で追加されました。

:glob:

toctreeのエントリでglobワイルドカードを解析します。すべてエントリは利用可能なドキュメントのリストと照合され、一致するものがアルファベット順にリストに挿入されます。例:

.. toctree::
   :glob:

   intro*
   recipe/*
   *

これには、まずintroで始まる名前のすべてのドキュメント、次にrecipeフォルダ内のすべてのドキュメント、最後に残りのすべてのドキュメント（ディレクティブを含むドキュメントを除く）が含まれます。[2]

バージョン0.3で追加されました。

:reversed:

リスト内のエントリの順序を逆転させます。:glob:オプションを使用する場合に特に便利です。

バージョン1.5で追加されました。

:hidden:

非表示のtoctreeは、ドキュメントの階層のみを定義します。ディレクティブの位置にドキュメントにリンクを挿入しません。

これは、手動リンク、HTMLサイドバーナビゲーションなど、他のナビゲーション手段がある場合、または最上位のtoctreeで:includehidden:オプションを使用する場合に有効です。

バージョン0.6で追加されました。

:includehidden:

完全なドキュメント構造を示すグローバルな目次を1つ作成する場合は、最上位のtoctreeディレクティブに:includehidden:オプションを追加します。子ページの他のすべてのtoctreeは、:hidden:オプションを使用して非表示にできます。:includehidden:を含む最上位のtoctreeには、それらのエントリが含まれます。

バージョン1.2で追加されました。

特別な名前

Sphinxは、独自の用途のためにいくつかのドキュメント名を予約しています。これらの名前のドキュメントを作成しようとしないでください。問題が発生します。

特別なドキュメント名（およびそれらに対して生成されるページ）は次のとおりです。

  • genindex

    これは、indexディレクティブとすべてのインデックス生成オブジェクトの説明からのエントリで移入される、一般インデックスに使用されます。例として、Sphinxの索引を参照してください。

  • modindex

    これは、py:moduleディレクティブごとに1つのエントリを含む、Pythonモジュールインデックスに使用されます。例として、SphinxのPythonモジュール索引を参照してください。

  • search

    これは、生成されたJSON検索インデックスとJavaScriptを使用して、生成されたドキュメントを検索語で全文検索するフォームを含む検索ページに使用されます。主要なブラウザすべてで動作します。例として、Sphinxの検索ページを参照してください。

  • _で始まるすべての名前

    現在Sphinxで使用されているそのような名前はほとんどありませんが、そのような名前のドキュメントまたはドキュメントを含むディレクトリを作成しないでください。（カスタムテンプレートディレクトリに_をプレフィックスとして使用することは問題ありません。）

警告

ファイル名に特殊文字を使用する際は注意してください。一部の形式では、これらの文字が予期しない方法で解釈される可能性があります。

  • HTMLベースの形式ではコロン:を使用しないでください。他の部分へのリンクが機能しない場合があります。

  • ePub形式ではプラス+を使用しないでください。一部のリソースが見つからない場合があります。

段落レベルのマークアップ

これらのディレクティブは短い段落を作成し、情報単位内と通常のテキストの両方で使用できます。

注意喚起、メッセージ、警告

注意喚起ディレクティブは「注意喚起」要素を作成します。これは、役立つtipから極めて重要なdangerまでのさまざまな種類の情報を伝えるための標準化されたシステムです。これらのディレクティブは、通常の本文要素が使用できる場所にどこでも使用でき、任意の本文要素を含めることができます。9個の特定の名前付き注意喚起と、一般的なadmonitionディレクティブがあります。

.. attention::

読者の注意が必要な情報。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

注意

皆様のご注意をお願いいたします。

.. caution::

読者が注意を払うべき情報。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

注意

十分な注意を払ってください。

.. danger::

注意しないと、差し迫った危険につながる可能性のある情報。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

危険

誰も危険を回避しようと思わないでください。なぜなら、遅かれ早かれ愛は彼自身の復讐者だからです。

.. error::

何らかの故障モードに関する情報。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

エラー

エラー418：私はティーポットです。

.. hint::

読者にとって役立つ情報。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

ヒント

植木鉢の下を見てください。

.. important::

非常に重要な情報であり、読者は無視しないでください。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

重要

これは非常に重要な記述です。

.. note::

読者が知っておくべき特に重要な情報。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

注意

この関数は、スパムの缶詰を送信するのに適していません。

.. tip::

読者にとって役立つちょっとした情報。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

ヒント

日焼け止めを忘れないでください！

.. warning::

読者が十分に認識しておくべき重要な情報。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

警告

犬に注意してください。

.. admonition:: title

オプションのタイトル付きの一般的な注意喚起。ディレクティブの内容は完全な文で記述し、適切な句読点をすべて含める必要があります。

例

これはタイトルです

これは注意喚起の内容です。

.. seealso::

多くのセクションには、モジュールドキュメントまたは外部ドキュメントへの参照のリストが含まれています。これらのリストは、seealsoディレクティブを使用して作成されます。

seealsoディレクティブは、通常、サブセクションの直前のセクションに配置されます。seealsoディレクティブの内容は、1行であるか、reStructuredTextの定義リストである必要があります。

例

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

こちらも参照

モジュール zipfile

標準モジュール zipfile のドキュメント。

GNU tar マニュアル、基本的な Tar 形式

GNU tar 拡張を含む、tar アーカイブファイルのドキュメント。

バージョン間の変更点の説明

.. versionadded:: version [brief explanation]

このディレクティブは、記述された機能が追加されたプロジェクトのバージョンを文書化します。モジュール全体またはコンポーネント全体に適用される場合は、関連するセクションの先頭で、本文の前に配置する必要があります。

最初の引数は必須で、対象となるバージョンです。変更内容の *簡単な* 説明からなる2番目の引数を追加できます。

注意

ディレクティブの見出しと説明の間に空行を入れてはいけません。これは、マークアップにおいてこれらのブロックを視覚的に連続させるためです。

例

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

バージョン 2.5 で追加: spam パラメータ。

.. versionchanged:: version [brief explanation]

versionadded と似ていますが、名前付き機能の変更時期と内容（新しいパラメータ、変更された副作用など）を説明します。

例

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

バージョン 2.8 で変更: spam パラメータは、 теперь типа boson です。

.. deprecated:: version [brief explanation]

versionadded と似ていますが、機能が非推奨になった時期を説明します。代替手段をユーザーに伝えるためなど、*簡単な* 説明を追加することもできます。

例

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

バージョン 3.1 から非推奨: 代わりに spam() を使用してください。

.. versionremoved:: version [brief explanation]

versionadded と似ていますが、機能が削除された時期を説明します。代わりに何をすべきか、または機能が削除された理由を説明することもできます。

バージョン 7.3 で追加。

例

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

バージョン 4.0 で削除: spam() 関数はより柔軟であるため、代わりに使用してください。

表示に関する事項

.. rubric:: title

ルブリックは、文書の構造に対応しない非公式な見出しのようなものです。つまり、目次ノードは作成しません。

注意

ルブリックの *title* が「脚注」（または選択された言語の同等語）の場合、LaTeX ライターによってこのルブリックは無視されます。これは、脚注の定義のみを含むと想定され、空の見出しが作成されるためです。

オプション

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

クラス属性 を割り当てます。これは 一般的なオプション です。

:name: label (text)

ref を使用して参照できる暗黙のターゲット名です。これは 一般的なオプション です。

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

バージョン 7.4.1 で追加。

このオプションを使用して、ルブリックの見出しレベルを指定します。この場合、ルブリックは HTML 出力に対して <h1> から <h6> としてレンダリングされるか、LaTeX の対応する番号なしセクション化コマンドとしてレンダリングされます（latex_toplevel_sectioning を参照）。

.. centered::

このディレクティブは、中央揃えの太字テキストの行を作成します。

バージョン 1.1 から非推奨: この表示専用のディレクティブは、以前のバージョンのレガシーです。rst-class ディレクティブを代わりに使用し、適切なスタイルを追加してください。

.. hlist::

このディレクティブには、箇条書きリストを含める必要があります。ビルダーに応じて、複数のアイテムを水平方向に分散するか、アイテム間のスペースを減らすことで、よりコンパクトなリストに変換されます。

オプション

:columns: n (int)

列の数。デフォルトは 2 です。例:

.. hlist::
   :columns: 3

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

バージョン0.6で追加されました。

コード例を表示する

Sphinxでは、構文強調表示されたリテラルコードブロックを複数的方法で表示できます。

Doctest ブロックは、対話型の Python セッションを表示するためだけに使用できます。残りの 3 つの方法は、他の言語にも使用できます。これらの 3 つのうち、リテラルブロックは、ドキュメント全体、または少なくともその大きなセクションが同じ構文のコードブロックを使用し、同じ方法でスタイル設定する必要がある場合に役立ちます。一方、code-block ディレクティブは、各ブロックのスタイル設定をより細かく制御する場合、または複数の異なる構文を使用するコードブロックを含むドキュメントがある場合に、より意味があります。最後に、literalinclude ディレクティブは、ドキュメントにコードファイル全体を含めるのに役立ちます。

いずれの場合も、構文の強調表示は Pygments によって提供されます。リテラルブロックを使用する場合、これはソースファイル内の任意の highlight ディレクティブを使用して構成されます。highlight ディレクティブが見つかると、次の highlight ディレクティブが見つかるまで使用されます。ファイルに highlight ディレクティブがない場合、グローバルな強調表示言語が使用されます。これはデフォルトで python ですが、highlight_language 構成値を使用して構成できます。次の値がサポートされています。

  • none （強調表示なし）

  • default （python3 に似ていますが、警告なしで強調表示が失敗した場合に none にフォールバックします。 highlight_language が設定されていない場合のデフォルト）

  • guess（Pygmentsに内容に基づいて字句解析器を推測させる。特定の容易に認識できる言語でのみ機能する）

  • python

  • rest

  • c

  • …その他、Pygmentsがサポートする字句解析器エイリアス

選択した言語での強調表示に失敗した場合（つまり、Pygmentsが「Error」トークンを出力した場合）、ブロックは一切強調表示されません。

重要

サポートされる字句解析器エイリアスのリストは、Pygmentのバージョンに依存します。強調表示の一貫性を確保したい場合は、Pygmentsのバージョンを固定する必要があります。

.. highlight:: language

例

.. highlight:: c

この言語は、次のhighlightディレクティブが検出されるまで使用されます。前述のように、languageはPygmentsがサポートする任意の字句解析器エイリアスにすることができます。

オプション

:linenothreshold: threshold (数値 (オプション))

コードブロックの行番号を生成するようにします。

このオプションは、しきい値パラメータとして数値をオプションで受け取ります。しきい値が指定されている場合、ディレクティブはN行より長いコードブロックに対してのみ行番号を生成します。指定されていない場合、すべてのコードブロックに対して行番号が生成されます。

例

.. highlight:: python
   :linenothreshold: 5
:force: (値なし)

指定されている場合、強調表示における軽微なエラーは無視されます。

バージョン2.1で追加されました。

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

例

.. code-block:: ruby

   Some Ruby code.

ディレクティブのエイリアス名sourcecodeも機能します。このディレクティブは引数として言語名を取ります。これはPygmentsがサポートする任意の字句解析器エイリアスです。指定されていない場合、highlightディレクティブの設定が使用されます。設定されていない場合、highlight_languageが使用されます。他のテキスト内にあるコード例を個別のブロックとしてではなく、インラインで表示するには、代わりにcodeロールを使用できます。

バージョン2.0で変更されました: language引数がオプションになりました。

オプション

:linenos: (値なし)

コードブロックの行番号を生成するようにします。

.. code-block:: ruby
   :linenos:

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

コードブロックの最初の行番号を設定します。存在する場合、linenosオプションも自動的に有効になります。

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

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

バージョン 1.3 で追加されました。

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

バージョン1.1で追加されました。

バージョン1.6.6で変更されました: LaTeXはemphasize-linesオプションをサポートするようになりました。

:caption: コードブロックのキャプション (テキスト)

コードブロックにキャプションを設定します。

バージョン 1.3 で追加されました。

:name: ハイパーリンクのラベル (テキスト)

refを使用して参照できる暗黙的なターゲット名を定義します。例えば

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

   print('Explicit is better than implicit.')

refまたはnumrefロールを使用してコードブロックをクロスリファレンスするには、**name**と**caption**の両方を定義する必要があります。**name**の引数は、クロスリファレンスを生成するためにnumrefに渡すことができます。例

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

refを使用する場合、明示的なタイトルが与えられれば、**name**のみが定義されている状態でクロスリファレンスを生成できます。例

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

バージョン 1.3 で追加されました。

:class: クラス名 (スペースで区切られたクラス名のリスト)

グラフのクラス名。

バージョン1.4で追加されました。

:dedent: 数値 (数値または値なし)

コードブロックからインデント文字を削除します。数値が指定されている場合、先頭のN文字が削除されます。引数が指定されていない場合、textwrap.dedent()を使用して先頭のスペースが削除されます。例

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

       some ruby code

バージョン 1.3 で追加されました。

バージョン3.5で変更されました: 自動デデントがサポートされました。

:force: (値なし)

指定されている場合、強調表示における軽微なエラーは無視されます。

バージョン2.1で追加されました。

.. literalinclude:: filename

プレーンテキストのみを含む外部ファイルに例テキストを格納することで、より長い逐語的なテキストの表示を含めることができます。literalincludeディレクティブを使用して、ファイルをインクルードできます。[3] 例えば、Pythonソースファイルexample.pyをインクルードするには、次のようにします。

.. literalinclude:: example.py

ファイル名は通常、現在のファイルのパスを基準とした相対パスです。ただし、絶対パス（/で始まる）の場合、最上位のソースディレクトリを基準とした相対パスになります。

追加オプション

code-blockと同様に、このディレクティブは、行番号をオンにするlinenosフラグオプション、最初の行番号を選択するlineno-startオプション、特定の行を強調表示するemphasize-linesオプション、暗黙的なターゲット名を指定するnameオプション、コードブロックからインデント文字を削除するdedentオプション、現在のファイルの標準言語とは異なる言語を選択するlanguageオプションをサポートしています。さらに、captionオプションもサポートしていますが、引数を指定せずにファイル名をキャプションとして使用することもできます。オプションを使用した例

.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:

必要なタブ幅でtab-widthオプションを指定すると、入力内のタブは展開されます。

source_encodingでファイルのエンコードが想定されています。ファイルが異なるエンコーディングを持つ場合は、encodingオプションで指定できます。

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

このディレクティブは、ファイルの一部のみを含めることもサポートしています。Pythonモジュールの場合、pyobjectオプションを使用して、含めるクラス、関数、またはメソッドを選択できます。

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

これにより、ファイル内のTimerクラスのstart()メソッドに属するコード行のみが含まれます。

あるいは、linesオプションを指定して、含める行を正確に指定することもできます。

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

これには、1行目、3行目、5行目から10行目、そして20行目から最終行が含まれます。

ファイルのどの部分をインクルードするかを制御する別の方法は、start-afterおよびend-beforeオプション（またはそのうちの1つのみ）を使用することです。start-afterが文字列オプションとして指定されている場合、その文字列を含む最初の行の後の行のみがインクルードされます。end-beforeが文字列オプションとして指定されている場合、その文字列を含む最初の行の手前の行のみがインクルードされます。start-atおよびend-atオプションは同様の動作をしますが、一致した文字列を含む行もインクルードされます。

start-after/start-atとend-before/end-atは同じ文字列を持つことができます。start-after/start-atは、オプション文字列を含む行の手前の行をフィルタリングします（start-atはその行を保持します）。次にend-before/end-atは、オプション文字列を含む行の後の行をフィルタリングします（end-atはその行を保持し、end-beforeは最初の行をスキップします）。

注意

次の例のように、iniファイルの[second-section]のみを選択する場合は、:start-at: [second-section]と:end-before: [third-section]を使用できます。

[first-section]

var_in_first=true

[second-section]

var_in_second=true

[third-section]

var_in_third=true

これらのオプションの有用なケースは、タグコメントを扱うことです。:start-after: [initialize]と:end-before: [initialized]オプションは、コメント間の行を保持します。

if __name__ == "__main__":
    # [initialize]
    app.start(":8000")
    # [initialized]

上記の方法のいずれかで行が選択された場合、emphasize-linesの行番号は、1から始まる連続した選択された行を参照します。

ファイルの特定の部分の表示を選択する場合、元の行番号を表示すると便利です。これはlineno-matchオプションを使用して行うことができますが、これは選択が連続した行からなる場合にのみ許可されます。

prependおよびappendオプションを使用して、それぞれインクルードされたコードの先頭と末尾に行を追加できます。これは、たとえば<?php/?>マーカーを含まないPHPコードを強調表示する場合に役立ちます。

コードの差分を表示したい場合は、diffオプションを指定して古いファイルを指定できます。

.. literalinclude:: example.py
   :diff: example.py.orig

これは、example.pyとexample.py.origの間の差分を、統一されたdiff形式で示しています。

forceオプションは、強調表示における軽微なエラーを無視できます。

バージョン 0.4.3 で変更: encodingオプションを追加しました。

バージョン 0.6 で変更: pyobject、lines、start-after、end-beforeオプションと、絶対ファイル名のサポートを追加しました。

バージョン 1.0 で変更: prepend、append、tab-widthオプションを追加しました。

バージョン 1.3 で変更: diff、lineno-match、caption、name、dedentオプションを追加しました。

バージョン 1.4 で変更: classオプションを追加しました。

バージョン 1.5 で変更: start-atおよびend-atオプションを追加しました。

バージョン 1.6 で変更: start-afterとlinesの両方が使用されている場合、start-afterによる最初の行は、linesに対して行番号1とみなされます。

バージョン 2.1 で変更: forceオプションを追加しました。

バージョン3.5で変更されました: 自動デデントがサポートされました。

用語集

.. glossary::

このディレクティブには、用語と定義を含むreStructuredTextの定義リストのようなマークアップが含まれている必要があります。その後、定義はtermロールを使用して参照できます。例

.. 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」として「key」を配置できます。例

.. glossary::

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

「key」はそのままグループ化キーとして使用されます。「key」は正規化されません。「A」と「a」は異なるグループになります。「key」内の文字全体が最初の文字の代わりに使用されます。「Combining Character Sequence」と「Surrogate Pairs」のグループ化キーに使用されます。

i18nの状況では、元のテキストに「term」部分しかない場合でも、「localized term : key」を指定できます。この場合、翻訳された「localized term」は「key」グループに分類されます。

バージョン 1.1 で変更: 用語に複数の用語とインラインマークアップがサポートされるようになりました。

バージョン 1.4 で変更: 用語集用語のインデックスキーは実験的とみなされるべきです。

オプション

:sorted:

エントリをアルファベット順にソートします。

バージョン0.6で追加されました。

バージョン 4.4 で変更: 国際化されたドキュメントでは、翻訳された用語に従ってソートします。

メタ情報マークアップ

.. sectionauthor:: name <email>

現在のセクションの作者を特定します。引数には、プレゼンテーションに使用できる作者の名前とメールアドレスを含める必要があります。アドレスのドメイン名部分は小文字にする必要があります。例

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

デフォルトでは、このマークアップは出力に何らかの形で反映されません（貢献状況の追跡に役立ちます）。ただし、構成値show_authorsをTrueに設定して、出力が段落を生成するようにすることができます。

.. codeauthor:: name <email>

codeauthorディレクティブは複数回表示でき、記述されているコードの作者を名前で指定します。sectionauthorがドキュメントの作者を指定するのと同じです。これも、show_authors構成値がTrueの場合にのみ出力が生成されます。

索引生成マークアップ

Sphinxは、ドメインで説明されているように、すべてのオブジェクトの説明（関数、クラス、属性など）から自動的に索引エントリを作成します。

ただし、索引をより包括的にし、言語リファレンスなど、情報が主に情報単位に含まれていないドキュメントで索引エントリを有効にするために、明示的なマークアップも用意されています。

.. index:: <entries>

このディレクティブには、1つ以上の索引エントリが含まれています。各エントリは、コロンで区切られたタイプと値で構成されます。

例

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

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

...

このディレクティブには5つのエントリが含まれており、生成された索引のエントリに変換され、索引ステートメントの正確な位置（またはオフラインメディアの場合は対応するページ番号）にリンクされます。

索引ディレクティブはソース内のその位置に相互参照ターゲットを生成するため、上記のように、参照するものの（例：見出し）前に配置するのが理にかなっています。

可能なエントリタイプは次のとおりです。

single

単一の索引エントリを作成します。セミコロンでサブエントリテキストを区切ることで、サブエントリにすることができます（この表記は以下でも、作成されるエントリを説明するために使用されます）。例

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

  • single: executionは、executionというラベルの付いた索引エントリを作成します。

  • single: execution; contextは、executionのcontextというラベルの付いたサブエントリを作成します。

pair

2つの索引エントリを作成するためのショートカットです。値のペアはセミコロンで区切る必要があります。例

.. index:: pair: loop; statement

これにより、loop; statementとstatement; loopという2つの索引エントリが作成されます。

triple

3つの索引項目を作成するためのショートカット。3つの値はすべてセミコロンで区切る必要があります。例

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

これにより、module; search path、search; path, module、およびpath; module searchの3つの索引項目が作成されます。

参照

別の項目を参照する索引項目を作成するためのショートカット。例

.. index:: see: entry; other

これにより、entryからotherを参照する索引項目が作成されます（つまり、「entry」：参照「other」）。

参照（複数）

seeと同様ですが、「see」の代わりに「see also」を挿入します。

モジュール、キーワード、演算子、オブジェクト、例外、文、組み込み関数

これらの**非推奨**のショートカットはすべて、2つの索引項目を作成します。例えば、module: hashlibは、module; hashlibとhashlib; moduleという項目を作成します。

バージョン1.0より非推奨: これらのPython固有の項目タイプは非推奨です。

バージョン7.1で変更: 削除バージョンがSphinx 9.0に設定されました。これらの項目タイプを使用すると、indexカテゴリで警告が出力されるようになりました。

感嘆符を前に付けることで、「メイン」索引項目をマークアップできます。「メイン」項目への参照は、生成された索引で強調表示されます。例えば、2つのページに

.. index:: Python

と、1つのページに

.. index:: ! Python

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

「単一」項目のみを含む索引ディレクティブには、ショートハンド表記があります。

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

これにより、4つの索引項目が作成されます。

バージョン1.1で変更: seeおよびseealsoタイプ、ならびにメイン項目のマークアップを追加しました。

オプション

:name: ハイパーリンクのラベル (テキスト)

refを使用して参照できる暗黙的なターゲット名を定義します。例えば

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

バージョン3.0で追加。

:index:

indexディレクティブはブロックレベルのマークアップであり、次の段落の先頭にリンクしますが、リンクターゲットを直接設定する対応するロールもあります。

ロールの内容は単純なフレーズにすることができ、これはテキストに保持され、索引項目として使用されます。また、テキストと索引項目の組み合わせにすることもでき、相互参照の明示的なターゲットと同様にスタイル設定されます。その場合、「ターゲット」部分は、上記ディレクティブについて説明されている完全な項目になります。例

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

バージョン1.1で追加されました。

タグに基づいてコンテンツを含める

.. only:: <式>

式がtrueの場合にのみ、ディレクティブのコンテンツを含めます。式は、次のようなタグで構成する必要があります。

.. only:: html and draft

未定義のタグはfalse、定義済みのタグはtrueです（タグは、--tagコマンドラインオプションまたはconf.py内で定義できます。こちらを参照）。ブール式（例：(latex or html) and draft）がサポートされており、括弧を使用できます。

現在のビルダーの形式と名前（html、latex、またはtext）は、常にタグとして設定されます[4]。形式と名前の違いを明確にするために、format_とbuilder_というプレフィックスも付けられます。たとえば、epubビルダーはhtml、epub、format_html、builder_epubというタグを定義します。

これらの標準タグは、設定ファイルの読み込み後に設定されるため、設定ファイル内では使用できません。

すべてのタグは、識別子とキーワードのドキュメントに記載されている標準的なPython識別子構文に従う必要があります。つまり、タグ式は、Python変数の構文に準拠したタグのみで構成できます。ASCIIでは、これは大文字と小文字のAからZ、アンダースコア_、そして最初の文字を除く0から9の数字で構成されます。

バージョン0.6で追加されました。

バージョン1.2で変更: ビルダーの名前とプレフィックスを追加しました。

警告

このディレクティブは、ドキュメントのコンテンツのみを制御するように設計されています。セクション、ラベルなどは制御できません。

表

reStructuredTextの表を使用します。つまり、

tableディレクティブは、gridおよびsimple構文のオプションのラッパーとして機能します。

HTML出力では問題なく動作しますが、LaTeXへの表のレンダリングは複雑です。latex_table_styleを確認してください。

バージョン1.6で変更: 複数の段落、ブロック引用、リスト、リテラルブロックなど、複雑なコンテンツを含むグリッド表のセル（複数行、複数列、両方）のマージが、LaTeX出力に正しくレンダリングされるようになりました。

.. tabularcolumns:: 列仕様

このディレクティブは、ソースの次の表のLaTeX出力のみに影響します。必須の引数は、列仕様（LaTeXの慣習では「配置前文」として知られています）。このような列仕様の基本については、wikiページなどのLaTeXドキュメントを参照してください。

バージョン0.3で追加されました。

注意

tabularcolumnsは、表ディレクティブの:widths:オプションと競合します。両方が指定されている場合、:widths:オプションは無視されます。

Sphinxは、30行を超える表をlongtableでレンダリングします。l、r、c、p{width}列指定子の他に、\X{a}{b}（バージョン1.5で新規追加）を使用することもできます。これは、列幅を合計行幅の分数a/bに設定し、\Y{f}（バージョン1.6で新規追加）ではfは小数です。たとえば\Y{0.2}は、列が行幅の0.2倍を占めることを意味します。

このディレクティブが30行以下の表に使用されている場合、Sphinxはtabularyでレンダリングします。その後、特定の列タイプL（左揃え）、R（右揃え）、C（中央揃え）、J（両端揃え）を使用できます。これらはp{width}（つまり、各セルは指定された内部テキストの配置と自動計算されたwidthを持つLaTeXの\parbox）の効果を持ちます。

警告

  • オブジェクトの説明、ブロック引用、あらゆる種類のリストなど、リストのような要素を含むセルは、LRCJ列タイプと互換性がありません。列タイプは、明示的なwidth（または\X{a}{b}または\Y{f}）を持つp{width}である必要があります。

  • リテラルブロックは、tabularyではまったく機能しません。Sphinxはtabularまたはlongtable環境にフォールバックし、適切な列仕様を生成します。

tabularcolumns ディレクティブが存在せず、テーブルの行数が30行以下で、上記の警告で説明されている問題のあるセルがない場合、Sphinx はすべての列にtabularyとJ列タイプを使用します。

バージョン 1.6 で変更: 以前はL列タイプ（テキストは左寄せ）が使用されていました。これを元に戻すには、LaTeX のプリアンブルに\newcolumntype{T}{L}を含めます。実際、Sphinx はTを使用し、デフォルトでJのエイリアスとして設定しています。

ヒント

tabularyのよくある問題として、内容の少ない列が「圧縮」されて見えることがあります。最小列幅を40ptにするには、例えば\setlength{\tymin}{40pt}をLaTeXプリアンブルに追加できます。tabularyのデフォルトの10ptは小さすぎることがあります。

ヒント

LaTeX のlongtable環境の使用を強制するには、table、csv-table、またはlist-tableに:class:オプションとしてlongtableを渡します。他のテーブルにはrst-classを使用します。

数式

数式の入力言語はLaTeXマークアップです。これはプレーンテキストの数式表記の事実上の標準であり、LaTeX出力を作成する際に追加の変換が必要ないという利点もあります。

autodocによって読み取られる**Python docstring**に数式マークアップを配置する場合、すべてのバックスラッシュを二重にするか、Pythonのraw文字列（r"raw"）を使用する必要があります。

.. math::

表示される数式（行全体を使用する数式）のためのディレクティブです。

このディレクティブは複数の数式をサポートしており、空行で区切る必要があります。

.. math::

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

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

さらに、各数式はsplit環境内に設定されます。つまり、数式内に&で揃えられ\\で区切られた複数の揃えられた行を含めることができます。

.. math::

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

詳細については、AmSMath LaTeXパッケージのドキュメントを参照してください。

数式が1行だけのテキストの場合は、ディレクティブ引数として指定することもできます。

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

オプション

:class: class 名 (class 名のリスト、空白で区切られる)

クラス属性 を割り当てます。これは 一般的なオプション です。

:name: ラベル (テキスト)

ref を使用して参照できる暗黙のターゲット名です。これは 一般的なオプション です。

:label: ラベル (テキスト)

通常、数式には番号は付けられません。数式に番号を付けるには、labelオプションを使用します。指定すると、数式の内部ラベルが選択され、それによって相互参照が可能になり、数式番号が付与されます。eqを参照してください。番号付けのスタイルは出力形式によって異なります。

:nowrap:

与えられた数式を数式環境で折り返さないようにします。このオプションを指定する場合は、数式が適切に設定されていることを自分で確認する必要があります。例えば

.. math::
   :nowrap:

   \begin{eqnarray}
      y    & = & ax^2 + bx + c \\
      f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}

こちらも参照

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

HTMLビルダーによる数式のレンダリングオプション。

latex_engine

数式マークアップでUnicodeリテラルをサポートするようにLaTeXビルダーを構成する方法について説明します。

文法生成表示

形式文法の生成を表示するための特別なマークアップが用意されています。このマークアップはシンプルで、BNF（または派生形式）のすべての側面をモデル化しようとするものではありませんが、コンテキストフリー文法を、記号の使用がその記号の定義へのハイパーリンクとしてレンダリングされるような方法で表示できるようにするのに十分な機能を提供しています。このディレクティブがあります。

.. productionlist:: [productionGroup]

このディレクティブは、生成のグループを囲むために使用されます。各生成は1行で指定され、コロンで区切られた名前とそれに続く定義で構成されます。定義が複数行にわたる場合は、継続行の先頭に、最初の行と同じ列にコロンを配置する必要があります。productionlistディレクティブの引数内では空行は許可されません。

定義には、解釈済みテキストとしてマークされたトークン名を含めることができます（例：「sum ::= `integer` "+" `integer`」）。これにより、これらのトークンの生成への相互参照が生成されます。production list の外では、tokenを使用してトークンの生成を参照できます。

productionlistへのproductionGroup引数は、異なる文法に属する異なる生成リストの集合を区別するために役立ちます。したがって、同じproductionGroupを持つ複数の生成リストは、同じスコープ内のルールを定義します。

production list の内部では、トークンは暗黙的に現在のグループからの生成を参照します。他の文法の生成を参照するには、トークンの前にそのグループ名とコロンを付けることができます（例：「otherGroup:sum」）。トークンのグループを生成に表示しない場合は、チルダを前に付けることができます（例：「~otherGroup:sum」）。名前のない文法からの生成を参照するには、トークンの前にコロンを付ける必要があります（例：「:sum」）。

production list の外側で、productionGroup引数を指定した場合は、相互参照内のトークン名の前にグループ名とコロンを付ける必要があります（例：「myGroup:sum」ではなく「sum」）。グループをリンクのタイトルにも表示しない場合は、明示的なタイトルを指定するか（例：「myTitle <myGroup:sum>」）、ターゲットの前にチルダを付けることができます（例：「~myGroup:sum」）。

生成内では、それ以上のreStructuredTextのパースは行われないため、*や|文字をエスケープする必要はありません。

以下は、Pythonリファレンスマニュアルからの例です。

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

脚注