SphinxのモジュールをPython以外のドメインに拡張することは可能ですか？

Question

私はVHDLソースコードを文書化するためにSphinxを使用したいと考えています。理想的には私はこのようなVHDLの種類を取るできるようにしたいと思います：

type T_SDRAM_REQ is record 
    req  : STD_LOGIC; 
    wr  : STD_LOGIC; 
    address : STD_LOGIC_VECTOR; 
    wr_data : STD_LOGIC_VECTOR; 
    wr_ben : STD_LOGIC_VECTOR; 
end record T_SDRAM_REQ; 

そして、このようなRSTディレクティブなものを使用します。ソースコードからすべてのフィールドを抽出するには

.. vhdl:type:: sdram_pack.T_SDRAM_REQ is record 
    :members: 

をし、 RST-私のためにそれらをify。

私はSphinxドメインを作成しましたが、これだけでは十分ではないということが私にもたらされました。これは本当にカスタムディレクティブの集まりです。私が実際に望むのは、パイロットのソースファイルをスキャンしてディレクティブを生成するautoclassやautomoduleに似たものです。

しかし、私がスフィンクスの自動モジュール機能に言えるのは、単にPython用です。 Sphinxを拡張して他の言語にも同様の機能を組み込むことは可能ですか？ VHDLでは、おそらくautopackageまたはautoentityと呼ばれるだろうC++では、私はautonamespaceか別のオートクローズを推測するでしょうか？どうにか私のドメインにvhdl:autopackage::ディレクティブを追加できますか？私がSphinxソースから知ることから、私はautomoduleディレクティブがPythonドメインの一部ではないと思います。

Answer 1

私自身の質問に対する答えは「はい」です。私はそれをすることができましたが、それは簡単ではなかったし、結果は完璧ではありません。

Sphinx Domain APIにはいくつかの一般的な基底クラスとPython固有のサブクラスが設定されていますが、autodocについては言いません。 Python autodocクラスの中には、基本クラスとして使うことができるものがありますが、多くのオーバーライドが必要です。

私autodocのシステムのコンポーネントは、次のとおりです。開始から：

• 新しいディレクティブVHDLAutoDirective、AutoDirectiveのサブクラス、それはドキュメント作成者および特別attrgettersに別々のレジストリを維持し、トリム「オートVHDL」 "auto"の代わりにディレクティブの名前を使用します。オリジナルと同様に、オブジェクト固有のドキュメンテーションを呼び出します。
• 新しい文書作成者。 1つの汎用VHDLドキュメントベースの基本クラスVHDLDocumenterは、各VHDLオブジェクトのサブクラスです。これらのドキュメント作成者は、重い持ち上げ、指示からのオプションとコンテンツの取得、VHDLの解析によるコンテンツの生成のすべてを行います。ここでの重要な問題は、Pythonのautodocが、インストールされていることを文書化しているモジュールに依存していることです。 SphinxはPythonで書かれているので、importモジュールをインストールして、必要な情報をすべて抽出するのはとても簡単です。例えば、__doc__を使ってdoctringsを抽出することができます。他の言語については、まず文書化したいオブジェクトを含むファイルを見つけて解析する必要があります。最初の問題を解決するために、後続のすべての自動ディレクティブにファイルを指定するためのcurrent-fileディレクティブと、ディレクティブごとにファイルを指定できるようにするためにdocumenterベースクラスのfileオプションを追加しました。ファイルのパスは私のリポジトリのベースと相対的なものであり、Sphinxがそこで実行されていることを前提としています.Sphinxをサブディレクトリで実行すると動作しません。 2番目には、生のソースコードをcode-blockというディレクティブにコピーするほうがいいかもしれないと思う前に、私は初歩的なトークナイザーとパーサを書いていました。
• 私のドメイン内のadd_autodocumenter機能は、ドメインにディレクティブを登録してから、自分のautodocモジュールをインポートし、add_documenter関数を呼び出してドキュメンテーションを登録します。 autodocモジュールのsetup関数は、autoディレクティブを使用して、各オブジェクトdocumenterのadd_autodocumenterを呼び出します。これはPythonのautodocの機能と似ていますが、Pythonのバージョンでは、ドメインではなくアプリにディレクティブが登録されています。

改善の余地はまだありますが、少なくともこれを行うことが可能であるという概念の証明となります。