sphinx-build fail - autodoc no puede importar / buscar módulo

Estoy tratando de empezar con Sphinx y parece que tengo problemas implacables.

Mando: docs/sphinx-quickstart

Respondo todas las preguntas y todo funciona bien.

Mando: docs/ls

Todo parece normal. Resultado:build Makefile source

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

Parece funcionar. Pude abrir el archivo index.html y ver un "shell" de lo que quiero.

Cuando trato de poner mi código fuente real como la sourcecarpeta, tengo problemas.

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

Resultado:

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!

Soy un novato completo en Sphinx y relativamente nuevo en este tipo de documentación. ¿Alguien puede ofrecer algunas sugerencias?

Editar:

Me gustaría poder usar un Makefile para manejar esto. A partir de ahora tengo dos carpetas en mi proyecto.

nextgen/ls

docs ys_utils

Necesito nextgen/docs/Makefilegenerar el HTML ys_utilsy todos los demás módulos que voy a tener.

Autodoc no puede encontrar sus módulos porque no están en sys.path.

Tienes que incluir la ruta a tus módulos sys.pathen tu conf.py. Mire en la parte superior de su conf.py(justo después de la importación de sys), hay una sys.path.insert()declaración, que puede adaptar.

Por cierto: puedes usar el Makefilecreado por Sphinx para crear tu documentación. Solo llama

make

para ver las opciones.

Si algo salió mal antes de intentarlo:

make clean

antes de correr make html.

Parece que os.path.append()está funcionando bien para la gente, pero si sigue la conf.pyplantilla, debe insertar la ruta del módulo al frente del sys.pathuso os.path.insert(0, ...)y simplemente agregar un extra.

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

Si ha configurado su sphinxproyecto para usar directorios separados buildy source, esa llamada debería ser:

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

en conf.py

simplemente agregue la ruta a la carpeta de su proyecto.

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

Si

1. La ruta raíz del módulo está configurada correctamente en conf.py
2. __init__.py está colocado correctamente
3. la primera sintaxis es correcta

y su autodoc todavía no puede encontrar los módulos ...

Puede deberse a que las dependencias de esos módulos no se satisfacen en su entorno de Python. Querrá comprobar si todas las declaraciones de importación funcionan dentro de los módulos.

Creo que hice esto la primera vez que intenté agregar un archivo al árbol. Creo que fue porque dejé la línea en blanco entre la línea: maxdepth y el nombre del archivo.

.. 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`

Arriba está mi archivo index.rst. stuff.rst reside en el mismo directorio que él.

Recibí este mismo error, pero fue causado por una razón completamente diferente a la explicada en las otras respuestas.

Mi .. automethod:: mymodule.funcdirectiva debería haber sido en realidad:

.. automethod:: mymodule::func`

Puede utilizar el formato Pweave y noweb para generar los primeros documentos que incluyan la salida del código incrustado en ellos. Básicamente, escribe su primer archivo, con el código Python incrustado en fragmentos marcados como este:

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

y Pweave ejecutará esos fragmentos y los reemplazará con su salida en un primer archivo resultante, que luego puede usar con sphinx. Vea el ejemplo de Pweave reST para obtener más detalles sobre su apariencia.