用語集

ビルダー

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

See Builders for an overview over Sphinx's built-in builders.

設定ディレクトリ

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

ディレクティブ

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

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

   Content of the directive.

See ディレクティブ for more information.

ドキュメント名

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

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

ドメイン

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

ドメインがあるということは、C++とPythonの両方のクラスに言及したいようなドキュメントを書く場合でも、名前が衝突する問題がない、ということです。まったく新しい言語のドキュメントをサポートするのも簡単になります。

For more information, refer to Domains.

環境

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

extension

A custom role, directive or other aspect of Sphinx that allows users to modify any aspect of the build process within Sphinx.

For more information, refer to 拡張.

マスタードキュメント

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

オブジェクト

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

RemoveInSphinxXXXWarning

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

ロール

A reStructuredText markup element that allows marking a piece of text. Like directives, roles are extensible. The basic syntax looks like this: :rolename:`content`. See インラインマークアップ for details.

ソースディレクトリ

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

reStructuredText

An easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system.