esfinge acumulación falle - autodoc no puede importar/encontrar el módulo

Question

que estoy tratando de empezar a trabajar con la esfinge y parecen tener problemas implacables.

Comando: docs/sphinx-quickstart

contesto todas las preguntas y todo funciona bien.

Comando: docs/ls

todo se ve normal. Resultado: build Makefile source

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

parece que funciona. Pude abrir el archivo index.html y ver un "caparazón" de lo que quiero.

Cuando intento poner mi código fuente real como la carpeta source me encuentro con problemas.

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

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

Editar:

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

nextgen/ls

docs ys_utils

necesito nextgen/docs/Makefile para generar el código HTML para ys_utils y todos los demás módulos que voy a tener.

Answer 1

creo que lo hice la primera vez que traté de añadir un archivo a la toctree. Creo que fue porque dejé fuera 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.

Answer 2

Autodoc no puede encontrar sus módulos, debido a que no están en sys.path.

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

Por cierto: puede usar el Makefile creado por Sphinx para crear su documentación. Sólo tiene que llamar

make 

para ver las opciones.

Si algo salió mal antes de intentarlo:

make clean 

antes de ejecutar make html.

Answer 3

en conf.py

sólo tiene que añadir la ruta de la carpeta del proyecto.

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

Answer 4

Esfinge no es muy compatible python3, corriendo __import__(module_name)Yimportlib.import_module(module_name) tanto trabajo en mi intérprete, pero no en la esfinge.

Intenté verificar la rama principal de sphinx, cambié mi intérprete a python3.4 en el Makefile y obtuve errores en los módulos que se eliminaron en la serie 3.x. Se puede ver mi informe cuestión aquí:

https://github.com/sphinx-doc/sphinx/issues/2046

Answer 5

se puede utilizar Pweave y formato noweb para generar documentos primeros que incluyen la salida del código incrustado en ellas. Básicamente, se escribe el archivo de primera, con el código Python incrustado en trozos marca así:

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

y Pweave ejecutará esos trozos, y reemplazarlos con su salida en un archivo primero resultante, que luego se puede utilizar con esfinge. Consulte el Pweave reST example para obtener más detalles sobre cómo se ve.

Answer 6

Intenté usar autodoc para documentar mi código de esfinge, pero omitiría uno de mis archivos porque no hice una clase dentro de ese archivo. Esto es lo que el archivo originalmente parecía algo como esto:

""" 
testing autodoc - this should be first line in doc 
""" 
import simulator 
world = simulator.simulator() 
#some more code... 

Este archivo nunca sería documentado con éxito por sphinx. Para llegar a ser documentado, que tenía que hacer lo siguiente:

""" 
testing autodoc - this should be first line in doc 
""" 
import simulator 

class runme(): 
    def __init__(self): 
    world = simulator.simulator() 
    #some more code... 


if __name__ == "__main__": 
    runme() 

Por lo tanto, parece que la Esfinge se requiere para envolver todos sus archivos en una clase para conseguir que se documentan. Espero que ayude, porque pasé horas tratando de descubrir por qué Sphinx no estaba documentando

Answer 7

Parece que os.path.append() está funcionando bien para la gente, pero si sigues la plantilla conf.py, insertarías la ruta del módulo al frente de sys.path usando os.path.insert(0, ...), y sólo tiene que añadir un extra de .

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

Si ha configurado su proyecto sphinx utilizar por separado bulid y source directorios, esa llamada debe ser en su lugar:

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