48

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サイトパッケージファイルの変更を伴うソリューションには近づかないようにしたいと思います。

4

3 に答える 3

44

そのような遅い答えを申し訳ありませんが（それがそれと見なすことができる場合）、私はあなたに何が起こっているのかを議論するこのリンクを見つけました：

https://github.com/phn/pytpm/issues/3#issuecomment-12133978

autosummaryがすでに実行された後にautosummaryドキュメントを作成しているドキュメントコードに特別なDocスクレーパーがある場合、この問題がまだ発生している場合は、調査する必要があるかもしれません。しかし、これがどれほど役立つかはわかりません。

リンクからの鍵は、以下を追加することですnumpydoc_show_class_members = False。conf.py

于 2013-03-04T20:46:22.790 に答える
11

numpydoc拡張機能を使用している場合は、それを削除してsphinx.ext.napoleon代わりに使用することを検討できます。

バージョン1.3以降、NumpyおよびGoogleスタイルのdocstringは、実際にはこの組み込み拡張機能によってサポートされています。

したがって、を削除numpydocして使用sphinx.ext.napoleonするconf.pyと、おそらく問題が解決します。

ソース

于 2017-04-05T17:30:05.020 に答える
9

私もこの問題に遭遇し、これに何時間も費やしました。次のことが私のために働きました：

スフィンクスはうるさいことがあり、時にはあなたが予期していなかったことについてです。たとえば、次のようなものに遭遇します。

WARNING: toctree contains reference to nonexisting document u'all-about-me'
...
checking consistency...
<your repository>/my-first-docs/docs/all-about-me.rst::
WARNING: document isn't included in any toctree'

おそらく、ここで起こったことは.. toctree::、Sphinxが3つを期待しているときに、4つのスペースで私のすべてをインデントしたことです。

ソース：ドキュメント！

于 2019-05-20T14:46:44.620 に答える