用語集

ビルダー

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

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

設定ディレクトリ

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の両方のクラスに言及したいようなドキュメントを書く場合でも、名前が衝突する問題がない、ということです。まったく新しい言語のドキュメントをサポートするのも簡単になります。

詳しくは、 Domains を参照してください。

環境

ルート以下のすべてのドキュメントの情報が格納される場所です。この情報はクロスリファレンスを作成する際に利用されます。この環境には、パース段階の後の結果のpickleされたものが入ります。ソースファイルが新規で作成されたり、変更されて、読み込んだりパースする必要がない限りはこの中のデータが更新されることはありません。

拡張

Sphinxのカスタム role 、 directive 、またはその他の側面で、Sphinx内のビルドプロセスの任意の側面を変更できます。

詳しくは、 拡張 を参照してください。

マスタードキュメント

ルートとなる toctree ディレクティブを含むドキュメントです。

root document

Same as master document.

オブジェクト

Sphinxドキュメントを構築する、基本構成単位です。すべての "オブジェクトディレクティブ"(function, object)はこのユニットを作成します。ほとんどのオブジェクトに対して、クロスリファレンスを行えます。

RemoveInSphinxXXXWarning

SphinxのXXXバージョンでこの機能が削除される警告です。通常、Sphinx拡張で利用しているAPIが非推奨となった場合等に発生します。参考: Deprecation Warnings.

ロール

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

ソースディレクトリ

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

reStructuredText

平文markup構文とparserシステムで、読みやすく、見たまま、見たまま、手に入れたままです。