Sphinxを使用して大規模なPythonコードベースのAPIドキュメントを自動的に作成しようとしています。
build_modules.pyとsphinx-apidocを使用してみました。どちらを使用しても、パッケージとトップレベルモジュールの出力ディレクトリに最初のドキュメントを正常に作成できます。
ただし、を使用してビルドする場合
make html
このタイプの何千ものエラーが発生します。
<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'
コードベース内のすべての単一のクラスとメソッドに対して。いくつかの実験で、autosummary / autoclassディレクティブが、すべてのクラスとメソッドに最初のファイルがあることを期待するtoctreeを作成していることを発見したと思います。
警告以外は、ドキュメントはうまく機能しているようですが、私はそれらを取り除きたいので、何かを誤って構成した可能性があると思います。
私もほぼ同じ効果でnipype/toolsを試しました。
apigen.pyとbuild_modref_templates.pyを変更して、これらの「欠落している」ドキュメントごとに、必要に応じてautoclass / autofunction/automethodsを使用して最初のスタブを作成しました。ただし、ビルドには非常に長い時間(10分)がかかり、最後のビルドステップでのメモリエラーが原因で最終的にクラッシュします。
すべての警告を作成するモジュールのrstファイルの例を次に示します。
src Package
===========
:mod:`src` Package
------------------
.. automodule:: src.__init__
:members:
:undoc-members:
:show-inheritance:
:mod:`Example1` Module
------------------------------------
.. automodule:: src.Example1
:members:
:undoc-members:
:show-inheritance:
:mod:`Example2` Module
------------------
.. automodule:: src.Example2
:members:
:undoc-members:
:show-inheritance:
これらの警告を解決する方法についてアドバイスをありがとうございます!sphinxサイトパッケージファイルの変更を伴うソリューションには近づかないようにしたいと思います。