用語集

ビルダー

Builder を継承したクラスで、パースされたドキュメントを受け取り、それに対してアクションをします。通常、ビルダーは他の出力フォーマットへ、ドキュメントを変換しますが、壊れたリンクのチェックを行ったり、情報のカバレッジを計測したり、といった用途にも使用できます。

Sphinxの内蔵のビルダーに関しては、 利用可能なビルダー のドキュメントを参照してください。

設定ディレクトリ
conf.py を含むディレクトリです。デフォルトでは、 ソースディレクトリ と同じですが、-c コマンドラインで別のディレクトリも設定できます。
ディレクティブ

reSturcturedTextのマークアップの要素で、特別な意味を持つコンテンツのブロックを表現できます。ディレクティブはDocutils由来のものだけでなく、Sphinx、カスタムの拡張機能によって定義されたものも使用できます。基本的なディレクティブの文法は次のようになります:

.. directivename:: argument ...
   :option: value

   Content of the directive.

より詳しい情報は ディレクティブ を参照してください。

ドキュメント名

reSTのソースファイルにはいくつかの拡張子を付けることができます。 .txt と付けるのが好きな人もいますし、 .rst を好む人もいます。Sphinxの中では source_suffix で拡張子を設定できます。また、OSによっては、パスの区切り文字が変わります。そのため、Sphinxではこれを抽象化して、 ドキュメント名 として、 ソースディレクトリ からの相対パスで、拡張子は省略し、区切り文字にスラッシュを利用するように変換されます。ドキュメントが来ることを期待する値、パラメータなどは、すべてこのようなドキュメント名が渡されるのを期待します。

ドキュメント名のサンプルとしては、 index, library/zipfile, reference/datamodel/types などがあります。前後のスラッシュは完全に省略されることに注意して下さい。

ドメイン

ドメインは、特定のプログラミング言語の要素などの オブジェクト の説明をしたり、リンクを張ったりするような、マークアップ(reSturucturedTextの ディレクティブ, ロール)を集めたものです。ドメインに属するディレクティブとロールの名前は、 py:function のように ドメイン:名前 となります。

ドメインを使用すると、ドキュメント内でC++とPythonの両方のクラスに言及したい場合などに、名前の衝突の問題を避けることができます。また、まったく新しい言語のドキュメント作成をサポートする拡張機能も作りやすくなります。ドメインに関する詳細な情報は、 Sphinxドメイン の章を参照してください。

環境
ルート以下のすべてのドキュメントの情報が格納される場所です。この情報はクロスリファレンスを作成する際に利用されます。この環境には、パース段階の後の結果のpickleされたものが入ります。ソースファイルが新規で作成されたり、変更されて、読み込んだりパースする必要がない限りはこの中のデータが更新されることはありません。
マスタードキュメント
ルートとなる toctree ディレクティブを含むドキュメントです。
オブジェクト
Sphinxドキュメントを構築する、基本構成単位です。すべての “オブジェクトディレクティブ”(function, object)はこのユニットを作成します。ほとんどのオブジェクトに対して、クロスリファレンスを行えます。
RemoveInSphinxXXXWarning
SphinxのXXXバージョンでこの機能が削除される警告です。通常、Sphinx拡張で利用しているAPIが非推奨となった場合等に発生します。参考: Deprecation Warnings.
ロール
reStuructredTextのマークアップの要素で、テキスト片にマーキングを行えます。ディレクティブと同様に、ロールも拡張できます。基本的な文法は次のようになります: :ロール名:`コンテンツ` 。詳しくは インラインマークアップ を参照してください。
ソースディレクトリ
ひとつのSphinxプロジェクトにおいて、すべてのソースファイルを含むディレクトリ。このディレクトリ直下だけではなく、サブディレクトリを使用してソースファイルを分類して入れておくことも可能です。