python - how - sphinx-build fail-autodoc no puede importar/encontrar módulo
sphinx python (7)
Estoy tratando de comenzar con Sphinx y parece tener problemas implacables.
Comando: docs/sphinx-quickstart
Respondo a 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 funcionar. Pude abrir el archivo index.html y ver un "shell" de lo que quiero.
Cuando intento poner mi código fuente real como la carpeta de 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!
Soy un novato de Sphinx y soy 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/Makefile para generar el HTML para ys_utils y todos los demás módulos que voy a tener.
Autodoc no puede encontrar sus módulos, porque no están en sys.path .
sys.path 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 puede adaptar.
Por cierto: puede usar el Makefile creado por Sphinx para crear su documentación. Solo llama
make
para ver las opciones.
Si algo salió mal antes de intentarlo:
make clean
Antes de ejecutar make html .
Creo que hice esto la primera vez que intenté agregar un archivo al toctree. 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 este.
Intenté usar Autodoc para documentar el código de mi esfinge, pero saltearía uno de mis archivos porque no formé una clase dentro de ese archivo. Esto es lo que el archivo originalmente se parecía a esto:
"""
testing autodoc - this should be first line in doc
"""
import simulator
world = simulator.simulator()
#some more code...
Este archivo nunca podría ser documentado con éxito por la esfinge. Para documentarlo, tuve 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()
Entonces, parece que Sphinx requiere que envuelvas todos tus archivos en una clase para documentarlos. Espero que eso ayude, porque pasé horas tratando de averiguar por qué Sphinx no estaba documentando
Parece que os.path.append() está funcionando bien para la gente, pero si sigue la plantilla conf.py , insertará la ruta del módulo al frente de sys.path usando os.path.insert(0, ...) , y solo agrega un extra .
import os
import sys
sys.path.insert(0, os.path.abspath(''..''))
Si ha configurado su proyecto de sphinx para usar directorios de source y bulid separados, esa llamada debería ser:
sys.path.insert(0, os.path.abspath(''../..''))
Puede usar el formato de Pweave y noweb para generar los primeros documentos que incluyen la salida del código incrustado en ellos. Básicamente, usted escribe su primer archivo, con el código de Python incrustado en fragmentos marcados como este:
<<echo=False>>=
print("some text that will appear in the rst file")
@
y Pweave ejecutará esos trozos y los reemplazará con su salida en un primer archivo resultante, que luego puede usar con la esfinge. Vea el ejemplo de Pweave reST para más detalles de cómo se ve.
Sphinx no es muy compatible con python3 , ejecutando __import__(module_name) Y importlib.import_module(module_name) ambos funcionan en mi intérprete, pero no en la esfinge.
Intenté verificar la rama maestra de la esfinge, 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. Puedes ver el informe de mi problema aquí:
en conf.py
simplemente agregue la ruta a su carpeta de proyecto.
sys.path.append(''/home/workspace/myproj/myproj'')