指令

As previously discussed 命令は明示的にラベル付けされた汎用ブロックである.Docutilsは多くのコマンドを提供し、Sphinxはより多くのコマンドを提供し、コマンドを主な拡張機構の1つとして使用する。

見 網域. ドメインごとに追加するための役割。

参考

参考にする reStructuredText Primer Docutilsが提供する指示の概要について。

カタログ.

RESTは、複数の文書を相互接続したり、文書を複数の出力ファイルに分割する機能を有していないため、Sphinxは、カスタム命令を使用して、文書を構成する単一のファイルとディレクトリとの間の関係を追加する。♪the toctree 指示は核心的な要素だ。

注釈

1つのファイルを他のファイルに簡単に“含める”ことができ、使用することができる include 指令する。

注釈

現在のドキュメント(.rstファイル)のディレクトリを作成するには、標準RESTを使用してください contents directive それがそうです。

.. toctree::

この命令は、命令ボリューム内で与えられた文書の各ディレクトリ(“サブディレクトリ木”を含む)を使用して、現在位置に“ディレクトリツリー”を挿入する。相対文書名(スラッシュで始まるのではない)は出現命令の文書に対して，絶対名はソースディレクトリに対するものである.1つの数字 maxdepth ツリーの深さを示すオプションを提供することができ、デフォルトでは、すべてのレベルを含む。 1

“TOCツリー”の表示は、出力フォーマットごとに変更されます。複数のファイルを出力するビルダ(例えば、HTML)は，ハイパーリンクの集合と見なす.一方、単一のファイルを出力するビルダ(例えば、LaTeX、マニュアルページなど)これをディレクトリ木上の文書内容に置き換える.

以下の例(Python文書からのライブラリ参照インデックス)を考える：

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

これで2つのことができます

  • これらすべての文書のリストは挿入され，最大深さは2つであり，これは1つの入れ子見出しを意味する. toctree このような文書の指示も考慮されている。

  • 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

中の文書タイトル toctree 引用文書のタイトルから自動的に読み込む.これがあなたが望むものでなければ、RESTハイパーリンク(およびSphinxの)と類似した文法を使用して、明確なタイトルおよびターゲットを指定することができます。 cross-referencing syntax ）。これはこう見えます

.. toctree::

   intro
   All about strings <strings>
   datatypes

上の2行目は strings 文書は、タイトル“All About String”ではなく、タイトル“All About String”を使用します strings 書類です。

また、HTTP URLを提供することで、文書名ではなく外部リンクを追加することができます。

横断面番号

HTML出力にも節番号があることをご希望でしたら、お出しください 最上階. Toctree a numbered 選択します。例えば：

.. toctree::
   :numbered:

   foo
   bar

そして、番号はタイトルから始まります foo それがそうです。サブディレクトリ木は自動的に番号付けされます(与えないでください numbered 旗をあの人たちに渡す)。

深さを数値パラメータとして与えることで，深さ番号を特定の深さに番号付けることもできる. numbered それがそうです。

オプションを追加する

ご利用いただけます caption オプションはtoctreeタイトルを提供しますので、ご利用いただけます name オプションは、使用によって使用可能な暗黙的ターゲット名を提供します。 ref **

.. toctree::
   :caption: Table of Contents
   :name: mastertoc

   foo

ツリー内の文書のタイトルのみを表示したい場合には、同一レベルの他のタイトルを表示しない場合には、使用することができる titlesonly オプション：：

.. toctree::
   :titlesonly:

   foo
   bar

Toctreeコマンドで“globbining”を使用することができます glob マークオプション。そして、すべてのエントリを利用可能な文書リストとマッチングし、一致項目をアルファベット順にリストに挿入する。例：：

.. toctree::
   :glob:

   intro*
   recipe/*
   *

これにはまず名前で始まるすべての文書が含まれている intro 中のすべての文書 recipe フォルダは，次にすべての残りの文書である(もちろん，命令を含む文書は除く). 2

特殊項目名 self Toctree命令を含む文書を表す.Toctreeから“サイトマップ”を生成したいなら、これは有用です。

ご利用いただけます reversed リスト内のエントリ順序を反転させるためのフラグオプション。これは使っています glob ファイル順序を反転させるためのフラグオプション。例：：

.. toctree::
   :glob:
   :reversed:

   recipe/*

以下に示すように、指示に“隠蔽”オプションを指定することもできます。

.. toctree::
   :hidden:

   doc_1
   doc_2

これは依然としてSphinx文書階層に通知されるが，コマンドが存在する位置でリンクを文書に挿入することはない-自分が異なるスタイルやHTML側の欄にこれらのリンクを挿入しようとする場合には意味がある.

トップディレクトリツリーを持ち、他の下位レベルのすべてのディレクトリツリーを隠したい場合は、トップディレクトリツリーエントリに“include deide”オプションを追加することができます。

.. toctree::
   :includehidden:

   doc_1
   doc_2

その後、“隠蔽”オプションによって他のすべてのディレクトリツリーエントリを除去することができる。

最後に文書中の全ての文書は source directory (またはサブディレクトリ)はいくつかに出現しなければならない toctree 命令；Sphinxが含まれていないファイルを発見した場合、標準ナビゲーションを介してファイルにアクセスできないことを意味するので、警告を発するであろう。

使用 exclude_patterns 文書やディレクトリは明示的に構築から完全に排除される.使用 the "orphan" metadata 文書の構築は許可されているが，Sphinxはtoctreeでその文書にアクセスできないことを通知する.

“マスター文書”(から master_doc )はディレクトリ木の階層構造の“根”である.文書のホームページとして使用することもでき、“完全なディレクトリ”としても使用することができる(与えられなければ maxdepth 選択します。

バージョン 0.3 で変更: “球形”オプションが追加されました。

バージョン 0.6 で変更: “番号”と“隠れ”オプション、外部リンクと“自己”引用のサポートが追加されています。

バージョン 1.0 で変更: “titlesonlyのみ”オプションが追加されました。

バージョン 1.1 で変更: “Numed”にデジタルパラメータを追加した.

バージョン 1.2 で変更: “include deidden”オプションが追加されました。

バージョン 1.3 で変更: “タイトル”と“名前”オプションが追加されました。

特殊名称.

Sphinxは自分で使用するためのいくつかの文書名を保持しています；これらの名前を使用して文書を作成しようとしてはいけません--これは問題になります

特殊文書名(およびそれのために生成されたページ)は：

  • genindex, modindex, search

    これらは、それぞれ通常のインデックス、Pythonモジュールインデックス、および検索ページに使用されます。

    汎用インデックスはモジュールからのエントリによって埋め込まれ，これらのすべてのエントリはインデックスによって生成される. object descriptions 他にもあります index 指令する。

    Pythonモジュールインデックスはそれぞれ1つのエントリを含む py:module 指令する。

    検索ページには，生成されたJSON検索インデックスとJavaScriptを用いて生成された文書を全文検索して検索語を検索するフォームが含まれており，現代のJavaScriptをサポートする各主要ブラウザ上で動作可能であるはずである.

  • 全ての名前は _

    Sphinxが現在使用しているこのような名前は少ないですが、そのような名前を使用して文書または文書を含むディレクトリを作成すべきではありません。(使用) _ カスタムテンプレートディレクトリのプレフィックスとしてあればよい).

警告

ファイル名の異常な文字に注意してください。いくつかのフォーマットは予期せぬ方法でこれらの文字を説明するかもしれません：

  • コロンの使用はご遠慮ください : HTMLベースのフォーマットに用いられる.他の部品へのリンクは機能しない可能性がある.

  • プラス番号を使わないでください + EPubフォーマットについて。特定の資源が見つからないかもしれない。

段級標

これらの命令は短い段落を作成し，情報ユニット内部で使用することも可能であり，通常のテキストにも利用可能である.

.. note::

APIの特に重要な情報については，ユーザはアノテーションに関連するAPIを使用する際に注意すべきである.命令の内容は，完全な文を用いて書かれ，すべての適切な句読点を含む.

例：：

.. note::

   This function is not suitable for sending spam e-mails.
.. warning::

APIのいくつかの重要な情報については、ユーザは、警告に関連するAPIを使用する際に非常に注意すべきである。命令の内容は，完全な文を用いて書かれ，すべての適切な句読点を含む.これは違います note 私たちはあなたが note 安全に関する情報を得る。

.. versionadded:: version

本命令は、説明された機能をライブラリまたはC APIに追加するプロジェクトバージョンを記録する。これがモジュール全体に適用される場合、それはモジュール部分の上部に置かれ、任意の散文の前に置かれなければならない。

第1のパラメータを提供しなければならず、このパラメータは問題のあるバージョンであり、第2のパラメータを追加することができる。 簡略化する. 変更の解釈。

例：：

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

命令ヘッドと解釈との間に空の行があってはならないことに留意されたい；これは、これらのブロックをマーク内で視覚的に連続させるためである。

.. versionchanged:: version

似たような versionadded しかし，名前付け機能の変更時間や変更内容(新しいパラメータ，変更の副作用など)が何らかの形で記述されている.

.. deprecated:: version

似たような versionchanged ただし、この機能が破棄される時間について説明する。例えば、読者に何を代替すべきかを説明することもできる。例：：

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

多くの部分は、モジュール文書または外部文書への参照リストを含む。これらのリストは seealso 指令する。

♪the seealso 命令は通常，どの子節の前にも1つの節に置かれる.HTML出力に対しては，テキストの主流から離れて表示される.

というメッセージを返します。 seealso 指示はREST定義リストでなければならない。例：：

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

もう一つ許可された“略語”はこう見えます

.. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`

バージョン 0.5 で追加: 略語形式。

.. rubric:: title

この命令は、ディレクトリノードを作成するために使用されない段落タイトルを作成する。

注釈

もし タイトル 引用語が“脚注”(または選択された言語の等価物)である場合、ラテックス作成者は、脚注定義のみを含むと仮定しているので、空の見出しを作成することができるので、ラテックス作成者は引用語を無視するであろう。

.. centered::

この指示は真ん中の太字テキスト行を作成する。使用方法は以下のとおりである.

.. centered:: LICENSE AGREEMENT

バージョン 1.1 で非推奨: これはデモのみの指示であり、古いバージョンのレガシーコンテンツである。使用 rst-class 指示し、適切なパターンを追加します。

.. hlist::

この命令はアイテム記号リストを含まなければならない。これは、構築器によって、複数の項目を水平に分布させることによって、または項目間の間隔を減少させることによって、よりコンパクトなリストに変換されるであろう。

水平分布をサポートする構築器には columns 列数を指定するオプション；デフォルトは2である.例：：

.. hlist::
   :columns: 3

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

バージョン 0.6 で追加.

表示コード例

構文的に強調表示された文字コードブロックをSphinxに表示する方法は様々である：使用 reST doctest blocks 使用する reST literal blocks 選択することができます highlight 命令を使う code-block 命令を使う literalinclude 指令する。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

  • それは.他にも `lexer alias that Pygments supports`_ _

選択された言語でハイライトに失敗した場合(すなわち、Pygmentsが“ERROR”フラグを発行する)場合、ブロックはいかなる方法でもハイライト表示されない。

重要

サポートする形態素解析器別名リストはPygmentバージョンに関連しているもしあなたが一貫したハイライトを確実にしたいなら、あなたはあなたのPygmentsバージョンを修復しなければならない。

.. highlight:: language

例：：

.. highlight:: c

この言語は次の年まで使われている highlight 指令する。前述したように、 言語 Pygmentsがサポートする任意の形態素解析器の別名であってもよい.

オプション

:linenothreshold: threshold (number (optional))

コードブロックのライン番号を生成するために有効になる。

このオプションは、閾値パラメータとしてオプションの数字を使用します。任意の閾値が与えられた場合、命令は、長さN行を超えるコードブロックについてのみ行番号を生成する。指定されていなければ，すべてのコードブロックに対して行番号を生成する.

例：：

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

所与の場合、強調表示された小さなエラーは無視されるだろう。

バージョン 2.1 で追加.

.. code-block:: [language]

例：：

.. code-block:: ruby

   Some Ruby code.

指令の別名 sourcecode 効果的ですこの命令は言語名をパラメータとする.これは，Pygmentsがサポートする任意の形態素解析器の別名であってもよい.指定されていなければ、 highlight 指示は使用されるだろう。設定されていなければ highlight_language 使用されます。

バージョン 2.0 で変更: ♪the language パラメータはオプションとなる.

オプション

:linenos: (no value)

コードブロックのライン番号を生成するために有効になる：

.. code-block:: ruby
   :linenos:

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

コードブロックの1行目の番号を設定する。もし存在すれば linenos オプションも自動的にアクティブになります：

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

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

バージョン 1.3 で追加.

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

符号ブロックの特定の行を強調する：

.. 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: caption of code block (text)

コードブロックのヘッダを設定する。

バージョン 1.3 で追加.

:name: a label for hyperlink (text)

以下のコマンドを使用して参照可能な暗黙的ターゲット名を定義する ref それがそうです。例えば：

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

   print 'Explicit is better than implicit.'

バージョン 1.3 で追加.

:dedent: number (number or no value)

コードブロックからインデント文字を剥離する.数字が与えられた場合、プリアンブルN文字が削除される。パラメータが与えられていない場合は、以下のようにプリアンブルスペースを削除します textwrap.dedent() それがそうです。例えば：

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

       some ruby code

バージョン 1.3 で追加.

バージョン 3.5 で変更: 自動降圧をサポートする。

:force: (no value)

所与の場合、強調表示された小さなエラーは無視されるだろう。

バージョン 2.1 で追加.

.. literalinclude:: filename

サンプルテキストをプレーンテキストのみを含む外部ファイルに格納することにより、より長い逐語テキスト表示を含むことができる。この書類は使用可能である literalinclude 指令する。 3 例えば、Pythonソースファイルを含む必要があります example.py 使用：

.. literalinclude:: example.py

ファイル名は、通常、現在のファイルに対するパスです。しかしもしそれが絶対的であれば / )は、上位ソースディレクトリに対して。

オプションを追加する

像 code-block この指示はサポートされています linenos 行番号を切り替えるためのフラグオプションは、 lineno-start 選択肢は最初の行番号を選択すると emphasize-lines 特定の行を強調するオプションは name 暗黙的なターゲット名を提供するためのオプションは、 dedent コードブロックのインデント文字を剥離するオプション、および1つ language オプションは、現在のファイル標準言語とは異なる言語を選択します。またそれは caption オプション；しかし、このオプションは、ファイル名をタイトルとして使用するために、パラメータを使用せずに提供されてもよい。以下のオプションを有する例：

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

もしあなたが1つ与えたら tab-width 必要なオプションカード幅を持つオプション。

ファイルコードを含むと仮定する source_encoding それがそうです。ファイルが異なる符号化を有する場合、使用することができる encoding オプション：：

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

その指示はまた文書の一部だけを含むことを支持する。Pythonモジュールであれば、含めるクラス、関数、または方法を選択することができます pyobject オプション：：

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

これには start() 方法中の Timer クラスはファイルで初期化されます。

あるいは1つを与えることで lines オプション：：

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

これには、1行目、3行目、5行目~10行目、20行目~最後の行が含まれる。

ファイルのどの部分を含むかを制御するもう1つの方法は使用である. start-after そして end-before オプション(またはそのうちの1つのみ)。もし start-after 文字列オプションとして提供される場合には、その文字列を含む1行目以降の行のみが含まれる。もし end-before 文字列オプションとして与えられると、その文字列を含む1行目の前の行のみが含まれる。♪the 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 1行目を飛び越える)。

注釈

もしあなたがただ選択したいなら [second-section] 以下に示すiniファイルについては、ご利用いただけます :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: [initialized] そして :end-before: [initialized] オプションは注釈の間に行を保持する：

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

上記のいずれかの方法で行を選択した後，中の行番号 emphasize-lines 選択された行を参照して、最初から連続してカウントします 1 それがそうです。

表示するファイルの特定の部分を指定する際には、元の行番号を表示することが有用である可能性がある。使用できる lineno-match オプションは、ただし、選択されたコンテンツが連続する行からなる場合にのみ、そのオプションの使用が許可される。

属性は，含まれるコードの前に1行追加および/または1行追加することができる prepend and append option, respectively. This is useful e.g. for highlighting PHP code that doesn't include the <?php/?> マーカーペン。

コードの違いを表示したい場合は、1つを与えることで diff オプション：：

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

これが示しているのは example.py そして example.py.orig 統一されたDIFFフォーマットを有する。

A force オプションは，強調表示時の小さなエラーを無視することができる.

バージョン 0.4.3 で変更: 追加 encoding 選択します。

バージョン 0.6 で変更: Added the pyobject, lines, start-after and end-before options, as well as support for absolute filenames.

バージョン 1.0 で変更: Added the prepend, append, and tab-width options.

バージョン 1.3 で変更: Added the diff, lineno-match, caption, name, and dedent options.

バージョン 1.5 で変更: 追加 start-at そして、 end-at 選択します。

バージョン 1.6 で変更: 両者を兼ねている. start-after そして lines 使用中、第1行根拠 start-after 行号を持っているとされている 1 上の lines それがそうです。

バージョン 2.1 で変更: 追加 force 選択します。

バージョン 3.5 で変更: 自動降圧をサポートする。

用語表

.. glossary::

この命令は、用語および定義を有するREST定義リスト形式のタグを含まなければならない。そしてこれらの定義は 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”にすることができます。例えば：

.. glossary::

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

キーをそのままグループ化するために“key”が用いられることに注意されたい.“キー”は正規化されておらず，キー“A”と“a”は異なるグループとなる.“キー”内の文字全体は、第1の文字の代わりに使用され、“結合文字シーケンス”および“エージェント対”グループキーに使用される。

I 18 Nの場合，オリジナルテキストが“Term”部分のみであっても，“Localized Term：Key”を指定することができる.この場合、翻訳後の“局所化用語”は“キーワード”のグループに格納される。

バージョン 0.6 で追加: 今は語彙表に指示を与えることができます :sorted: エントリを自動的にアルファベット順にソートするフラグ.

バージョン 1.1 で変更: 現在、複数の用語および用語における連結タグがサポートされている。

バージョン 1.4 で変更: 語彙表タームの索引キーを考慮すべきである 試験的に それがそうです。

メタ情報タグ

.. sectionauthor:: name <email>

現在の節の著者を識別する.パラメータは、プレゼンテーションおよび電子メールアドレスのために使用することができるように、著者の名前を含むべきである。アドレスのドメイン名部分は小文字でなければならない.例：：

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

デフォルトの場合、このフラグは出力に反映されませんが、設定値を設定することができます。 show_authors 至る True 出力に段落を作らせます

.. codeauthor:: name <email>

♪the codeauthor 命令は何度も現れることができます記述されたコードの著者を指定しています sectionauthor 命名文書の著者。出力は次のような場合にのみ生成されます show_authors 配置値は True それがそうです。

インデックス生成タグ

Sphinxは、上述したように、すべてのオブジェクト記述(関数、クラス、または属性など)に従ってインデックス項目を自動的に作成する 網域. それがそうです。

しかしながら、インデックスをより包括的にするために明示的なタグを使用してもよく、情報が主に言語参照のような情報ユニットに含まれない文書にインデックス項目を有効にすることもできる。

.. index:: <entries>

この命令は、1つまたは複数のインデックス項目を含む。各エントリは、コロンで分離された1つのタイプと1つの値から構成される。

例えば：

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

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

...

この命令は、生成されたインデックス内のエントリに変換される5つのエントリを含み、これらのエントリは、インデックス文の適切な位置(オフラインメディアである場合、対応するページ番号にリンクされる)にリンクされる。

インデックス命令は，それらがソースコード中の位置で交差参照先を生成するため，それらをインデックス命令に入れることは意味がある. その前に 彼らが言及しているもの-例えば、上の例のタイトル。

可能なエントリタイプは、

シングル

単一のインデックス項目を作成します。サブエントリテキストは、サブエントリテキストを記号で区切ることによってサブエントリにすることができる(以下、この記号も使用して、どのエントリが作成されたかを説明する)。

対になる

pair: loop; statement 2つのインデックス項目を作成するための迅速な方法です loop; statement そして statement; loop それがそうです。

三重

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: entry; other 以下の位置から参照される索引項目の作成 entry 至る other それがそうです。

また会いましょう

像 see ただし、“参照”ではなく“別途参照”を挿入します。

モジュール、キーワード、演算子、オブジェクト、異常、文、構築

これらは2つのインデックス項目を作成している。例えば module: hashlib エントリを作成する module; hashlib そして hashlib; module それがそうです。(それらはPython固有のものなので、廃棄されています。)

“Main”インデックス項目の前に感嘆符を付けることで、これらのインデックス項目をマークすることができます。生成されたインデックスでは、“主”エントリへの参照が強調される。例えば、2つのページが含まれている場合：

.. index:: Python

1ページには以下のようなものがあります

.. index:: ! Python

そして、3つの逆方向リンクのうち、次のページへの逆方向リンクが強調される。

“単一の”エントリのみを含むインデックス命令の場合、速記記号：

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

これは、4つのインデックス項目を作成します。

バージョン 1.1 で変更: 増列する. see そして seealso タイプ、およびメインエントリをマークします。

オプション

:name: a label for hyperlink (text)

以下のコマンドを使用して参照可能な暗黙的ターゲット名を定義する ref それがそうです。例えば：

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

バージョン 3.0 で追加.

:index:

当. index コマンドはブロックレベルでタグを付けて次段の先頭にリンクし，それを用いたリンク先を直接設定する対応する役割がある.

キャラクタの内容は、簡単なフレーズであってもよく、その後、テキストに保存され、インデックス項目として使用されてもよい。これは、交差参照の明示的なターゲットと同様のパターンを有するテキストとインデックスエントリとの組み合わせであってもよい。この場合、“ターゲット”部分は、上述した命令に記載された完全エントリであってもよい。例えば：

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

バージョン 1.1 で追加.

タグに基づく内容も含まれています

.. only:: <expression>

命令の内容は以下の場合にのみ含まれる 表示法 本当です。式は，以下のようにタグからなるべきである.

.. only:: html and draft

未定義のタグは偽で定義されたタグ(通過 -t コマンドラインオプションまたは conf.py 会いましょう here )すべて本当です。ブール式は、丸括弧(例えば、丸括弧)も用いられる html and (latex or draft) )は支持されています。

The format and the name of the current builder (html, latex or text) are always set as a tag 4. To make the distinction between format and name explicit, they are also added with the prefix format_ and builder_, e.g. the epub builder defines the tags html, epub, format_html and builder_epub.

これらの標準ラベルは設定されています その後 構成ファイルが読み取られたので、それらはそこでは使用できない。

すべてのラベルは、上記の標準Python識別子文法に従わなければなりません Identifiers and keywords 書類です。すなわち，トークン式にはPython変数文法に適合するタグのみが含まれている可能性がある.ASCIIでは大文字と小文字で構成されています A 通り抜ける Z 下に線を引く _ そして、最初の文字を除いて、数字は 0 通り抜ける 9 それがそうです。

バージョン 0.6 で追加.

バージョン 1.2 で変更: 建設業者の名前と接頭辞が追加されました。

警告

この指示は文書の内容のみを制御することを目的としている。それは部分、ラベルなどを制御できない。

時計

使用 reStructuredText tables どちらかというと

  • ネット·シート文法 (ref )、

  • 簡単表文法 (ref )、

  • csv-table 文法は

  • あるいは…。 list-table 文法です。

♪the table 指令が役割を果たす. grid そして 簡単 文法です。

これらはHTML出力ではよく動作しているが，LaTeXではテーブルを用いる際に列幅を自動的に正確に決定することが困難であるという問題がある.したがって，以下の命令が存在する.

.. tabularcolumns:: column spec

この命令は、ソースファイルに現れる次のテーブルの“列仕様”を与える。規範はLaTeXの2つ目の論点です tabulary パケットの環境(Sphinxは表を変換するために用いられる).これは次のような値を持つことができる：

|l|l|l|

これは3つの左側に調整された不連続な列があることを意味する。自動改行すべき長いテキストを持つ列については、基準をご利用ください p{{width}} 構造や表の自動説明子：

L

自動幅整列左欄を使用しております

R

自動幅整合右列

C

自動幅のある真ん中の列

J

自動幅の整列

の自動幅 LRCJ 列の属性は tabulary 1回目で観察されたシェアに比例して、第1回目では、表セルはその自然な“水平”幅で提示される。

デフォルトの場合、Sphinxはフォームレイアウトを使用します。 J 列ごとに。

バージョン 0.3 で追加.

バージョン 1.6 で変更: カスタマイズされたSphinx LaTeXマクロのおかげで，マージされたセルは現在複数のパラグラフを含むことができ，処理がはるかに良い.このような目新しい状況が彼を転向させた J 説明符と注釈 L デフォルトの場合。

ヒント

ライオンの顔像は実際に使われています T 説明符が完成しました \newcolumntype{{T}}{{J}} それがそうです。以前のデフォルト値に戻すには、挿入してください \newcolumntype{{T}}{{L}} LaTeX前書きにございます(参照) latex_elements ）。

表の一般的な問題の1つは、内容の少ない欄が“押しつぶされる”ことである。最小列幅は名が \tymin それがそうです。LaTeXプリアンブルに以下のようにグローバルに設定することができます \setlength{{\tymin}}{{40pt}} 例えば。

そうでなければ、ご利用ください tabularcolumns 明示的である. p{{40pt}} 例えば、この列に使用される。ご利用いただけます l 説明子は，あるマージされたセルがその列と交わると，列幅を設定するタスクをより困難にする.

警告

Tables with more than 30 rows are rendered using longtable, not tabulary, in order to allow pagebreaks. The L, R, ... specifiers do not work for these tables.

類似リストの要素(オブジェクト記述、ブロック引用符、または任意のタイプのリストのような)を含むテーブルは使用できない tabulary それがそうです。そのため、それらは標準的なラテックスでオーダーメイドされている。 tabular (または) longtable )環境を与えなければ tabularcolumns 指令する。そうすればテーブルの上に置かれています tabulary でもあなたは使用しなければなりません p{{width}} 構造(またはライオンの顔像) \X そして \Y 以下に説明する説明子)は、これらの要素を含む列のために使用される。

文字ブロックは適用されません tabulary したがって，文字ブロックを含む表はつねに使用される tabular それがそうです。文字ブロックのための逐語環境は，文字ブロックにのみ適用可能である. p{{width}} (に) \X あるいは…。 \Y )列であるので、Sphinxは文字ブロックを含む表がこのような列サイズを生成する。

Sphinx 1.5から始めます \X{{a}}{{b}} 説明子(存在)を用いた is 説明符文字の逆スラッシュ)。このように p{{width}} 幅を点数に設定した場合 a/b 前線が広い。あなたはいてもいい tabularcolumns もしLaTeXマクロを呼び出したら問題ではありません \X ()

そうなんです。 not 需要 b 列の総数でも，そうでもない \X 説明子を合わせると1となる.例えば |\X{{2}}{{5}}|\X{{1}}{{5}}|\X{{1}}{{5}}| 合法であり、テーブルは行幅の80%を占め、その3列の第1の列の幅は、後の2列の幅の和と同じである。

それは :widths: の選択肢です。 table 指令する。

Sphinx 1.6から始まり \Y{{f}} 10進パラメータの説明子を受け取る、例えば \Y{{0.15}} ：これは以下と同様の効果がある. \X{{3}}{{20}} それがそうです。

バージョン 1.6 で変更: 複雑なメッシュシート中のマージセル(複数行，多列または両者を兼ねている)は，現在，ブロック参照，リスト，文字ブロックなどを許可している.普通の細胞もそうです

Sphinx's merged cells interact well with p{width}, \X{a}{b}, \Y{f} and tabulary's columns.

注釈

tabularcolumns 与 :widths: 指示のオプションを表にする。両方とも指定すれば :widths: 選択肢は無視されるだろう。

数学.

数学の入力言語はLaTeXタグである.これは平文数学表現法の事実基準であり，LaTeX出力を構築する際にさらなる変換を必要としないという追加的な利点がある.

覚えておいてください数学的なマーカーを入れると Python文書文字列 読者を閲読する. autodoc 逆スラッシュを2倍にしたり、Python元の文字列を使用したりする必要があります (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 package それがそうです。

数学が1行のテキストしかない場合、命令パラメータとして与えることもできる：

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

通常，方程式は番号付けされていない.方程式を1つの数字にしてほしい場合は、ご利用ください 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

LaTeX生成器は、数学タグ内のUnicode文字をサポートするためにどのように構成されるかを説明する。

文法生成表示

特殊なタグは，形式文法の結果を表示するために用いることができる.このタグは簡単であり、BNF(または任意の派生フォーム)のすべての態様をモデル化しようとは試みていないが、提供されたタグは、記号の使用が記号定義へのハイパーリンクとして提示されるように、文脈自由文法を1つの方法で表示することを可能にするのに十分である。このような指示があります

.. productionlist:: [productionGroup]

この指示は製品のセットをカプセル化するために使用される。各製品は1行にあり，名称からなり，名称間はコロンで区切られており，以下のように定義される.定義が複数の行にまたがる場合、各継続行は、第1の行と同じ列に位置するコロンで開始されなければならない。

♪the 生産班. はいの論点です。 productionlist 異なる文法に属する異なるプロダクションリスト集合を区別するために用いられる.複数の生産リストは同じものを持つ 生産班. したがって，同一範囲でルールを定義する.

中に空きがあってはいけません productionlist 指令パラメータ。

定義は、解釈テキストとしてマークされたタグ名を含むことができる(例えば“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 それがそうです。しかしもしあなたが 生産班. パラメータの場合，交差参照では内識別名にプレフィックスとしてグループ名とコロンを付加しなければならず，たとえば，“``myGroup：sumsun`”ではなく，“``sumura`”だけではない.グループがリンクのタイトルに表示されるべきでない場合には、明確なタイトル(例えば、“``myTitle<myGroup：sum>`”)を与えることができ、またはターゲットの前に波浪番号を付けることができる(例えば、“~myGroup：sumura”)とすることができる。

製品ではさらなるREST解析は行われませんので、転義する必要はありませんのでご注意ください * あるいは…。 | 文字です。

以下は、“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`

脚注

1

Laexライタは引用のみ maxdepth 文書中の最初のtoctree命令のオプション。

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

これには標準的なものがあります .. include 指示は、しかし、そのファイルが見つからないと、エラーを引き起こす。これは警告するだけです。

4

ほとんどのビルダについては，名前とフォーマットは同じである.現在，HTMLビルダから派生するビルダのみがビルダ形式とビルダ名を区別している.

現在のビルダマークは使用できません conf.py これは、ビルダの初期化後にのみ利用可能である。