Sphinxの実行中にソースファイルを前処理する方法は？

Question

私は自分のプロジェクト用のSphinxのドキュメントを作成しており、ソースファイル用のドキュメント文字列を抽出して最終的なドキュメントに埋め込んでいます。残念ながら、ソースファイルの言語（VHDL）はSphinxではサポートされていません。 VHDL用のSphinxドメインは存在しないようです。スフィンクスに

• フックが（各ソースファイルから最上位の複数行をテキストブロックを抽出
• Pythonのコードスフィンクスの前にいくつかのPythonコードを実行し、実行します。次のように

  だから私のアイデアがありますコメントブロック）、このコメントブロックと他のreSTマークアップからなるソースファイルごとに1つのreSTファイルをアセンブルします。

• すべてのソースファイルはディレクティブを生成するためにindex.rstにリストされています。
• テキストの抽出と変換は、ソースコードディレクトリごとに再帰的に実行されます。

したがって、主な質問はです。どのようにしてSpinxに接続しますか？

conf.pyで自分の設定をインポートして実行するだけですか？

#!/usr/bin/env python3 
# -*- coding: utf-8 -*- 
# 
from my_preprocessor import my_proc 
proc = my_proc() 
proc.run() 
# 
# Test documentation build configuration file, created by 
# sphinx-quickstart on Tue May 24 11:28:20 2016. 
# .... 

私は、ビルドプロセスのファイルを変更することはできません：Makefileとmake.bat、実際のビルドプロセスがReadTheDocs.org上で実行されるため。 RTDはconf.pyのみ実行します。

Answer 1

私のこれまでのコメントとmertyildiranの答えで述べたように、言語のためにSphinxにフックする正式な方法は、VHDLの新しいドメインを実装するためにはcreate an extensionです。

これは他の多くの言語で既に行われています。 Erlang、PHP、CoffeeScript - APIなど - HTTP REST - ちょうどsphinx-contribからいくつかの名前を付ける。しかし、それはあなたが持っていない多くの時間がかかるでしょう...したがって、あなたはいくつかの迅速な構文解析を行い、それをあなたのスフィンクスビルドに何とかしていくオプションが残っています。

公式のフックをバイパスしているので、この質問は「自分のコードをSphinxビルド内でどのように実行するのですか？そのため、ローカル拡張のガイダンスに従うだけです。つまり、別のディレクトリに配置し、パスに追加してからインポートして呼び出すことをお勧めします。 docsで述べたように：

構成ファイルはビルド時にPythonコードとして実行される（execfileを（）を使用し、そしてそれを含むディレクトリに設定された現在のディレクトリを有する）、したがって、任意の複雑なコードを実行することができます。 Sphinxはファイルの名前空間からシンプルな名前を読み込みます。最終として

しかし、これはいくつかの概略図を作成する（mertyildiranの答えに再びうなずいて）pyVhdl2Schのようなサードパーティ製のパッケージを使用して、多分模式的に説明するために、その周りにあなたの静的rstファイルを書き込むためのオプションを開きます。

Answer 2

あなたはナットを割るためにスレッジハンマーを使用しようとしています。

スフィンクスは当初、新しいPythonドキュメント用に作成され、それがPythonのプロジェクトのドキュメントについて 優れた施設を持っていますが、 C/C++は、すでに同様にサポートされ、ために特別な のサポートを追加するために計画されました。他の言語も同様です。 http://www.sphinx-doc.org/en/stable/

VHDLは現在、スフィンクスによってサポートされている言語ではなく、VHDLのハードウェア記述言語であるため、サポートされている言語になるための優先順位が低くなければなりません。あなたは2つのオプションがありますし、最初のものはまた、あなたに私の提案です：

を

1）VHDL特定のドキュメント生成ツールを使用しての代わりに、スフィンクス VHDocL - http://www.volkerschatz.com/hardware/vhdocl.html

VHDLドキュメントユーティリティDoxygenに基づいてPerlで書かれています。

pyVhdl2Schからhttp://laurentcabaret.github.io/pyVhdl2Sch/

pyVhdl2Schは、ドキュメント生成ツールです。エントリとしてVHDLファイル（.vhd）を受け取り、各入力ファイル用のpdf/svg/ps/png回路図を生成します。純粋なPythonで書かれ、よりコミュニティフレンドリーで最新のものです。

SigasiメーカーXLドク - 商用製品であるSigasiメーカーのhttp://www.sigasi.com/products/

ハイエンド版。

2）はスフィンクスのプロジェクトに貢献し、フォローSphinx Developer's Guide VHDLドメインに

を追加し、プロジェクト構造に精通します。最終的にこのプロジェクトディレクトリにvhdl.pyを追加してください：https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains

この2番目のオプションは、StackOverflowの回答では説明できません。 Sphinxのようなオープンソースプロジェクトに機能を追加したいのはあなた次第です。