Sphinxを作成して、PydocからRSTクラスのドキュメントを生成します

Question

私は現在、既存の（不完全な）すべてのドキュメントをに移行しています スフィンクス.

問題は、ドキュメントが使用することです Python Docstrings （モジュールはCで記述されますが、おそらく問題ではありません）。クラスのドキュメントは、Sphinxに使用可能なフォームに変換する必要があります。

がある Sphinx.ext.autodoc, 、しかし、それは自動的に現在のdocstringsをドキュメントに入れます。でソースファイルを生成したい（rst）現在のDocstringsに基づいて、手動で編集および改善できます。

SphinxのためにDocstringsをRSTにどのように変換しますか？

Answer 1

AutoDocはRSTを生成します。それを引き出す公式の方法はありません。それを取得するのが最も簡単なハックは、変更することでした sphinx.ext.autodoc.Documenter.add_line それが得るラインを私に放出する方法。

私が望むのは一度限りの移行だけで、stdoutへの出力は私にとって十分です：

def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    print self.indent + line
    self.directive.result.append(self.indent + line, source, *lineno)

これで、AutoDocプリントは実行中にSTDOUTで最初に生成され、他の場所にリダイレクトまたはコピーするだけです。

Answer 2

モンキーパッチングautoDOCで、何も編集する必要なく動作します。

import sphinx.ext.autodoc
rst = []
def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    rst.append(line)
    self.directive.result.append(self.indent + line, source, *lineno)
sphinx.ext.autodoc.Documenter.add_line = add_line
try:
    sphinx.main(['sphinx-build', '-b', 'html', '-d', '_build/doctrees', '.', '_build/html'])
except SystemExit:
    with file('doc.rst', 'w') as f:
        for line in rst:
            print >>f, line

Answer 3

私が知る限り、これを行う自動化されたツールはありません。したがって、私のアプローチは、関連するモジュール（Sphinc.ext.autodocに基づいて）を読み取り、Doc文字列をファイル（適切にフォーマット）にスローする小さなスクリプトを作成することです。