用語集¶
- ビルダー¶
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システムで、読みやすく、見たまま、見たまま、手に入れたままです。