sphinx-build fail - autodoc can't import/find module

Question

J'essaie de démarrer avec Sphinx et j'ai l'impression d'avoir des problèmes incessants.

Commandement : docs/sphinx-quickstart

Je réponds à toutes les questions et tout fonctionne bien.

Commandement : docs/ls

Tout semble normal. Résultat : build Makefile source

Commandement : sphinx-build -d build/doctrees source build/html

Cela semble fonctionner. J'ai pu ouvrir le fichier index.html et voir une "coquille" de ce que je voulais.

Lorsque j'essaie d'insérer mon code source réel dans le champ source Je rencontre des problèmes.

Commandement : sphinx-build -d build/doctrees ../ys_utils build/html

Résultat :

Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
No builder selected, using default: html
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
Traceback (most recent call last):                                                                                               
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils.test_validate_ut
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils.git_utils
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named setup.setup

/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:4: WARNING: autodoc can't import/find module 'ys_utils', it reported error: "No module named ys_utils", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:10: WARNING: autodoc can't import/find module 'ys_utils.test_validate_ut', it reported error: "No module named ys_utils.test_validate_ut", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:12: WARNING: don't know which module to import for autodocumenting u'UnitTests' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:18: WARNING: autodoc can't import/find module 'ys_utils.git_utils', it reported error: "No module named ys_utils.git_utils", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:24: WARNING: autodoc can't import/find module 'setup.setup', it reported error: "No module named setup.setup", please check your spelling and sys.path
WARNING: master file /home/ricomoss/workspace/nextgen/ys_utils/index.rst not found
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 50%] index                                                                                                   
Exception occurred:
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/environment.py", line 1213, in get_doctree
    f = open(doctree_filename, 'rb')
IOError: [Errno 2] No such file or directory: '/home/ricomoss/workspace/nextgen/docs/build/doctrees/index.doctree'
The full traceback has been saved in /tmp/sphinx-err-jjJ7gM.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

Qu'est-ce qui ne va pas et comment puis-je y remédier ?

Editer :

J'aimerais pouvoir utiliser un Makefile pour gérer cela. Pour l'instant, j'ai deux dossiers dans mon projet.

nextgen/ls

docs ys_utils

J'ai besoin nextgen/docs/Makefile pour générer le code HTML pour ys_utils et tous les autres modules dont je disposerai.

Answer 1

Autodoc ne peut pas trouver vos modules, parce qu'ils ne sont pas dans sys.path .

Vous devez inclure le chemin d'accès à vos modules dans le fichier sys.path dans votre conf.py . Regardez en haut de votre conf.py (juste après l'importation de sys ), il existe un sys.path.insert() que vous pouvez adapter.

À propos : vous pouvez utiliser la fonction Makefile créé par Sphinx pour créer votre documentation. Appelez simplement

make

pour voir les options.

Si quelque chose n'a pas fonctionné avant l'essai :

make clean

avant l'exécution make html .

Answer 2

Solution

On dirait que os.path.append() fonctionne bien pour les gens, mais si vous suivez les instructions de l conf.py vous devez insérer le chemin d'accès au module à l'avant du modèle sys.path en utilisant os.path.insert(0, ...) et ajoutez simplement un .

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Si vous avez configuré votre sphinx afin d'utiliser des build y source cet appel doit être remplacé par :

sys.path.insert(0, os.path.abspath('../..'))

à propos de sys.path ...

Pour exécuter le code python, l'interpréteur python doit savoir où il se trouve. La configuration de sphinx étant un script python, son emplacement doit être connu, ce qui est fait en l'ajoutant à la balise sys.path à l'aide de la méthode d'insertion (voir la documentation sur les chemin de recherche du module ).

Le chemin ajouté à sys.path est un chemin "relatif", spécifié à l'aide de points. Il s'agit d'une façon générale de spécifier le chemin, qui permet de déplacer le code tout en pointant correctement vers le bon chemin dans votre base de code.

. - chemin actuel de la conf.py

.. - chemin parent de la conf.py

../.. - parent du chemin parent, etc.

J'utilise linux, donc les répertoires sont spécifiés avec une barre oblique, mais une méthode multiplateforme pour spécifier les répertoires parents peut être obtenue avec pathlib .

from pathlib import Path

parent = Path(__file__).parent
parents_parent = Path(__file__).parents[1]

Answer 3

En conf.py

il suffit d'ajouter le chemin d'accès au dossier de votre projet.

sys.path.append('/home/workspace/myproj/myproj')

Answer 4

Si

1. le module Root path est correctement défini dans conf.py
2. __init__.py est placé correctement
3. La première syntaxe est correcte

et votre autodoc ne trouve toujours pas les modules...

Il se peut que les dépendances de ces modules ne soient pas satisfaites dans votre environnement python. Vous devrez vérifier que toutes les déclarations d'importation fonctionnent dans les modules.

Answer 5

Je ne sais pas pourquoi (peut-être que dans mon cas, autodoc n'a pas pu installer mon paquet), mais j'ai toujours obtenu module-not-found jusqu'à ce que j'inclue explicitement tous les répertoires contenant des modules dans le chemin d'accès.

Pour l'exemple de structure de dossier suivant

project_dir
|- setup.py
|- src
|  |- __init__.py
|  |- source1.py
|  |- sub_project
|     |- __init__.py
|     |- source2.py 
|- docs
    |- conf.py
    |- source
    |  |- index.rst
    |- _build       

J'ai inclus

for x in os.walk('../../src'):
  sys.path.insert(0, x[0])

au début de conf.py de manière à ce que tous les répertoires concernés soient ajoutés.