用語集

ビルダー

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

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

ディレクティブ

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

.. ディレクティブ名:: 引数 ...
   :オプション: 値

   ディレクティブのコンテンツ

ドキュメント名

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)はこのユニットを作成します。ほとんどのオブジェクトに対して、クロスリファレンスを行うことができます。

ロール

reStuructredTextのマークアップの要素で、テキスト片にマーキングを行うことができます。ディレクティブと同様に、ロールも拡張することができます。基本的な文法は次のようになります: :ロール名:`コンテンツ` 。詳しくは インラインマークアップ を参照してください。

ソースディレクトリ

ひとつのSphinxプロジェクトにおいて、すべてのソースファイルを含むディレクトリ。このディレクトリ直下だけではなく、サブディレクトリを使用してソースファイルを分類して入れておくことも可能です。

設定ディレクトリ

conf.py を含むディレクトリ。デフォルトでは ソースディレクトリ と同じですが、 -c コマンドラインオプションを使用することで変更することができます。