web-dev-qa-db-fra.com

Sphinx autosummary "toctree contient une référence à un document inexistant"

J'essaie de créer automatiquement des documents api pour une grande base de code python en utilisant Sphinx.

J'ai essayé d'utiliser build_modules.py et sphinx-apidoc. Avec l'un ou l'autre, je peux obtenir les premiers documents créés avec succès dans mon répertoire de sortie pour les packages et les modules de niveau supérieur.

Cependant, quand je construis en utilisant

make html

cela donne des milliers d'erreurs de ce type:

<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'

pour chaque classe et méthode dans la base de code. Avec une certaine expérimentation, je pense avoir découvert que les directives autosummary/autoclass créent des toctrees qui s'attendent à ce qu'il y ait des premiers fichiers pour chaque classe et méthode.

Hormis les avertissements, la documentation semble bien fonctionner, mais j'aimerais m'en débarrasser et je pense que j'ai peut-être mal configuré quelque chose.

J'ai également essayé nipype/tools à peu près le même effet.

J'ai modifié apigen.py et build_modref_templates.py pour créer les premiers stubs pour chacun de ces documents "manquants", avec autoclass/autofunction/automethods selon le cas. Cependant, la génération prend un certain temps (10 minutes) et finit par se bloquer en raison d'erreurs de mémoire lors de la dernière étape de génération.

Voici un exemple de premier fichier de module qui crée tous les avertissements:

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:

Merci pour tout conseil sur la façon de résoudre ces avertissements! Je voudrais rester à l'écart de toute solution qui implique la modification des fichiers de package de site sphinx.

pythonpython-2.7python-sphinx
44
user1287170

Désolé pour une réponse si tardive (si cela peut être envisagé), mais j'ai trouvé ce lien qui discute de ce qui pourrait vous arriver:

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

L'idée que si vous avez un grattoir Doc spécial dans votre code de documentation qui crée une documentation de synthèse automatique après l'exécution de la synthèse automatique peut être quelque chose à examiner si vous rencontrez toujours ce problème. Cependant, je ne sais pas combien d'aide ce sera.

La clé du lien est d'ajouter: numpydoc_show_class_members = False à conf.py

43
djhoese

Si vous utilisez l'extension numpydoc, vous pouvez envisager de la supprimer et d'utiliser sphinx.ext.napoleon au lieu.

Depuis la version 1.3, les docstrings de style Numpy et Google sont en fait pris en charge par cette extension intégrée.

Suppression de numpydoc et utilisation de sphinx.ext.napoleon dans votre conf.py résoudra donc probablement votre problème.

Sources

10
Kurt Bourbaki

Je viens de rencontrer ce problème aussi et j'y passe des heures, ce qui suit a fonctionné pour moi:

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.

Source: docs !

3
0x78f1935