Sphinxの開発拡張

多くの項目の文書には特殊な機能が必要であるため，Sphinxは複数のレベルで拡張可能に設計されている.

以下は、拡張で実行できるいくつかの動作です。

  • 新しいものを追加する builder 解析された文書に対して新たな出力フォーマットや操作を実行することをサポートする。

  • カスタムreStruredTextロールとコマンドの登録、使用 DocutilsタグAPI それがそうです。

  • 構築過程全体で，キー位置でいわゆる“フック”にカスタムコードを追加し，フックを登録して専用コードを実行することを可能にする.例えば、参照してください ライオンの顔像の中心的な事件 それがそうです。

拡張はPythonモジュールです setup() 機能します。ユーザは拡張モジュールのモジュール名(またはサブモジュール)を入れることで extensions 値を配置する。

いつ？ sphinx-build このとき，Sphinxはリストされた各モジュールを導入し，実行することを試みる. yourmodule.setup(app) それがそうです。この関数は、拡張を準備するために使用され(例えば、Pythonコードを実行することによって)、Sphinxが構築中に使用するリソース(例えば、CSSまたはHTMLファイル)をリンクし、命令またはロール定義のようなSphinx拡張によって提供されるすべてを通知する。♪the app パラメータは Sphinx Sphinx構築の大部分を制御することができます

注釈

プロファイル自体に含まれている場合 setup() 機能します。ロードする他のすべての拡張は extensions 値を配置する。

このページの残りの部分は、開発拡張のいくつかの高度な態様と、あなたが制御することができるSphinx動作の様々な部分を説明します。拡張を構築し、拡張を使用してSphinxの異なる部分を制御する方法のいくつかの例については、参照されたい チュートリアルを拡張する それがそうです。

重要な対象

いくつかの重要なオブジェクトがありますが、拡張を作成する際にそれらのAPIを使用します。これらは

Application

アプリケーションオブジェクト(一般的には app )はい。 Sphinx それがそうです。これは、拡張された設定、イベント割り当て、および出力(ログ)のような大部分の高度な機能を制御する。

環境オブジェクトがあれば、アプリケーションは env.app それがそうです。

Environment

環境オブジェクトを生成する(通常は env )はい。 BuildEnvironment それがそうです。これは，ソース文書の解析を担当し，文書集合に関するすべてのメタデータを格納し，構築ごとにディスクに直列化する.

そのAPIは，メタデータへのアクセス，解析引用などの手法を提供する.拡張はまた、増分のために予約されるべき情報をキャッシュするために使用されてもよい。

アプリケーションやビルダオブジェクトがある場合は、以下のような形態で環境を提供することができます app.env あるいは…。 builder.env それがそうです。

Builder

生成器オブジェクト(一般には builder )は、特定のサブクラスのインスタンスである Builder それがそうです。各ビルダクラスは、解析された文書を出力フォーマットに変換する方法を知っているか、またはそれらを他の方法で処理する(例えば、外部リンクをチェックする)。

アプリケーションオブジェクトがあれば、以下のようにビルダを使用することができます app.builder それがそうです。

Config

配置オブジェクト(一般に呼ばれる config )に設定された構成値の値を提供する conf.py 属性として。これは一例です Config それがそうです。

この構成は以下のように得られる app.config あるいは…。 env.config それがそうです。

これらのオブジェクトの用法例を見るには、参照されたい チュートリアルを拡張する それがそうです。

構築段階

拡張メカニズムを理解するためには重要なことがありますSphinxプロジェクトを構築する方法ですいくつかの段階で動作しています

ステップ0：初期化

この段階では、私たちが関心を持っていることはほとんどない。ソースディレクトリでソースファイルを検索し、拡張子を初期化します。格納された構築環境が存在する場合は，その環境をロードし，そうでなければ新たな構築環境を作成する.

ステップ1：読む

ステップ1では、すべてのソースファイル(および後続の構築において、新しいまたは変更されたソースファイル)が読み取られて解析される。これはdocutilがコマンドとロールに遭遇して対応するコードを実行する段階である.この段階の出力は 文書木. 各ソースファイルについて；これはdocutilsノードからなる木である。すべての既存ファイルを読み込む前に完全に知られていない文書要素については、一時ノードが作成される。

Docutilsによって提供されるノードもあります文書にはこれらのノードが記録されています in the docutils documentation それがそうです。他のノードはSphinxと documented here それがそうです。

読み込み中に、読取文書のすべてのメタ参照データおよび交差参照データ(タグ、タイトル名、記述されたPythonオブジェクト、インデックス項目など)を用いて構築環境を更新します。これは、一時ノードの置換のために後で使用されるであろう。

解析された文書木はディスクに格納されており，それらをすべてメモリに保存することは不可能である.

ステップ2：一貫性チェック

構築された文書に意外がないことを確認するためにいくつかの検査を行った.

ステップ3：解決

すべての既存文書のメタデータおよび交差参照データが既知である以上，すべての一時ノードはノードに置き換えられ，これらのノードは変換と呼ばれるコンポーネントを用いて出力に変換することができる.たとえば，存在するオブジェクト参照のためのリンクを作成し，存在しないオブジェクト参照のために簡単な文字ノードを作成する.

ステップ4：書く

この段階では，解析された文書木をHTMLやLaTeXのような必要な出力形式に変換する.これは，各文書木の各ノードにアクセスし，その過程でいくつかの出力を生成するいわゆるdocutilsコンパイラによって実現される.

注釈

いくつかのビルダはこの一般的な構築計画から外れており，たとえば，外部リンクを検査するビルダは解析された文書木のみであるため，第2-4段階はない.

アプリケーションの例を見るには、参照してください “TODO”拡張の開発 それがそうです。

メタデータを拡張する

バージョン 1.3 で追加.

♪the setup() 関数は辞書に戻ることができる.Sphinxはこれを拡張メタデータと見なす.現在識別されているメタデータキーワードは、以下のことを含む。

  • 'version' ：拡張バージョンの文字列を識別します。拡張バージョン要求チェックに使用されています(参照 needs_extensions )と情報目的。あげなければ、 "unknown version" 取って代わられた。

  • 'env_version' ：拡張が任意のデータを環境に格納する場合、環境データ構造のバージョンを識別する整数。これは，前回の構築以来データ構造が変更されたかどうかを検出するために用いられる.データ構造が変更された場合、拡張はバージョンをインクリメントしなければならない。指定されていない場合、Sphinxは、拡張はいかなるデータも環境に格納しないと考える。

  • 'parallel_read_safe' ：1つのブール値であり，ロード拡張時に並列読み出しソースファイルを使用できるかどうかを指定する.デフォルト値は False すなわち，拡張が安全であるかどうかをチェックした後，並列読み出し安全であることを明示的に指定しなければならない.

  • 'parallel_write_safe' ：1つのブール値であり，ロード拡張時に出力ファイルを並列に書き込むことができるかどうかを指定する.拡張は通常プロセスに悪影響を与えないため，このデフォルト値は True それがそうです。