web-dev-qa-db-ja.com

Sphinx自動要約「toctreeには存在しないドキュメントへの参照が含まれています」警告

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分）、最後のビルドステップでのメモリエラーが原因で最終的にクラッシュします。

すべての警告を作成するモジュールの最初のファイルの例を次に示します。

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:

これらの警告を解決する方法についてアドバイスをありがとう！スフィンクスのサイトパッケージファイルの変更を伴うソリューションは避けたいと思います。

pythonpython-2.7python-sphinx
44
user1287170

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

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

Autosummaryがすでに実行された後にautosummary文書を構築しているドキュメンテーションコードに特別なDocスクレイパーがある場合、まだこの問題が発生している場合は、検討する必要があるかもしれません。ただし、これがどの程度役立つかはわかりません。

リンクからのキーは追加することです：numpydoc_show_class_members = False〜conf.py

43
djhoese

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

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

したがって、numpydocを削除し、sphinx.ext.napoleonでconf.pyを使用すると、問題が解決する可能性があります。

出典

10
Kurt Bourbaki

私もこの問題に遭遇し、これに何時間も費やしました。以下がうまくいきました：

Sphinx can be fussy, and sometimes about things you weren’t expecting. 
For example, you well encounter something like:

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'

Quite likely, what has happened here is that you indented all-about-me
in your .. toctree:: with four spaces, when Sphinx is expecting three.

出典： docs ！

3
0x78f1935