用語集

ビルダー

A class (inheriting from Builder) that takes parsed documents and performs an action on them. Normally, builders translate the documents to an output format, but it is also possible to use builders that e.g. check for broken links in the documentation, or build coverage information.

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のカスタム roledirective 、またはその他の側面で、Sphinx内のビルドプロセスの任意の側面を変更できます。

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

マスタードキュメント

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

オブジェクト

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

RemoveInSphinxXXXWarning

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

ロール

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

ソースディレクトリ

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

reStructuredText

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