échin de la construction de sphinx - autodoc ne peut pas importer / trouver le module

J'essaie de démarrer avec Sphinx et je semble avoir des problèmes incessants.

Commander: docs/sphinx-quickstart

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

Commander: docs/ls

Tout semble normal. Résultat:build Makefile source

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

Cela semble fonctionner. J'ai pu ouvrir le fichier index.html et voir un "shell" de ce que je veux.

Lorsque j'essaie de mettre mon code source réel dans le sourcedossier, je rencontre des problèmes.

Commander: 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!

Je suis un novice complet de Sphinx et relativement nouveau dans ce type de documentation. Quelqu'un peut-il offrir quelques suggestions?

Éditer:

J'aimerais pouvoir utiliser un Makefile pour gérer cela. À partir de maintenant, j'ai deux dossiers dans mon projet.

nextgen/ls

docs ys_utils

J'ai besoin nextgen/docs/Makefilede générer le HTML pour ys_utilset tous les autres modules que je vais avoir.

Autodoc ne trouve pas vos modules, car ils ne sont pas dans sys.path.

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

Au fait: vous pouvez utiliser le Makefilecréé par Sphinx pour créer votre documentation. Il suffit d'appeler

make

pour voir les options.

Si quelque chose ne va pas avant d'essayer:

make clean

avant de courir make html.

Cela semble os.path.append()fonctionner bien pour les gens, mais si vous suivez le conf.pymodèle, vous insérez le chemin du module au début de l' sys.pathutilisation os.path.insert(0, ...), et ajoutez simplement un supplément.

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

Si vous avez configuré votre sphinxprojet pour utiliser des répertoires buildet séparés source, cet appel devrait plutôt être:

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

dans conf.py

ajoutez simplement le chemin d'accès à votre dossier de projet.

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

Si

1. le chemin racine du module est correctement défini dans conf.py
2. __init__.py est placé correctement
3. la première syntaxe est correcte

et votre autodoc ne parvient toujours pas à trouver les modules ...

Cela peut être dû au fait que les dépendances de ces modules ne sont pas satisfaites dans votre environnement python. Vous voudrez vérifier si toutes les instructions d'importation fonctionnent dans les modules.

Je pense que je l'ai fait la première fois que j'ai essayé d'ajouter un fichier au toctree. Je pense que c'est parce que j'ai laissé de côté la ligne vide entre la ligne: maxdepth et le nom du fichier.

.. Animatrix Concepts documentation master file, created by
   sphinx-quickstart on Thu Mar 22 18:06:15 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Animatrix Concepts documentation!
============================================

Contents:

.. toctree::
   :maxdepth: 2

   stuff


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Ci-dessus, mon fichier index.rst. stuff.rst réside dans le même répertoire que lui.

J'ai eu cette même erreur mais elle a été causée par une raison complètement différente de celle expliquée dans les autres réponses.

Ma .. automethod:: mymodule.funcdirective aurait dû être:

.. automethod:: mymodule::func`

Vous pouvez utiliser le formatage Pweave et noweb pour générer des premiers documents qui incluent la sortie du code qui y est incorporé. En gros, vous écrivez votre premier fichier, avec du code python incorporé dans des morceaux marqués comme ceci:

<<echo=False>>=
print("some text that will appear in the rst file")
@

et Pweave exécutera ces morceaux, et les remplacera par leur sortie dans un premier fichier résultant, que vous pourrez ensuite utiliser avec sphinx. Voir l' exemple Pweave reST pour plus de détails sur son apparence.