sphinx-build fallisce - autodoc non può importare / trovare il modulo

Sto cercando di iniziare con Sphinx e sembra che abbia problemi implacabili.

Comando: docs/sphinx-quickstart

Rispondo a tutte le domande e tutto funziona bene.

Comando: docs/ls

Sembra tutto normale. Risultato:build Makefile source

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

Sembra funzionare. Sono stato in grado di aprire il file index.html e vedere una "shell" di quello che voglio.

Quando provo a inserire il mio codice sorgente effettivo come sourcecartella, mi imbatto in problemi.

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

Risultato:

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!

Sono un principiante assoluto di Sphinx e relativamente nuovo a questo tipo di documentazione. Qualcuno può offrire alcuni suggerimenti?

Modificare:

Mi piacerebbe poter usare un Makefile per gestirlo. Al momento ho due cartelle nel mio progetto.

nextgen/ls

docs ys_utils

Devo nextgen/docs/Makefilegenerare l'HTML per ys_utilse tutti gli altri moduli che avrò.

Autodoc non riesce a trovare i tuoi moduli, perché non sono in sys.path.

Devi includere il percorso dei tuoi moduli in sys.pathnel tuo file conf.py. Guarda all'inizio del tuo conf.py(subito dopo l'importazione di sys), c'è una sys.path.insert()dichiarazione, che puoi adattare.

A proposito: puoi usare il Makefilecreato da Sphinx per creare la tua documentazione. Chiama soltanto

make

per vedere le opzioni.

Se qualcosa è andato storto prima di provare:

make clean

prima di correre make html.

Sembra che os.path.append()funzioni bene per la gente, ma se segui il conf.pymodello, inseriresti il ​​percorso del modulo all'inizio sys.pathdell'uso os.path.insert(0, ...)e aggiungerai semplicemente un.

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

Se hai configurato il tuo sphinxprogetto per utilizzare directory separate builde source, quella chiamata dovrebbe invece essere:

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

nel conf.py

basta aggiungere il percorso alla cartella del progetto.

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

Se

1. il percorso di root del modulo è impostato correttamente in conf.py
2. __init__.py è posizionato correttamente
3. la prima sintassi è corretta

e il tuo autodoc ancora non riesce a trovare i moduli ...

Potrebbe essere perché le dipendenze di quei moduli non sono soddisfatte nel tuo ambiente python. Dovrai controllare se tutte le istruzioni di importazione funzionano all'interno dei moduli.

Penso di averlo fatto la prima volta che ho provato ad aggiungere un file a toctree. Penso che sia stato perché ho omesso la riga vuota tra la riga: maxdepth e il nome del file.

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

Sopra c'è il mio file index.rst. stuff.rst risiede nella stessa directory di esso.

Ho ricevuto lo stesso errore ma è stato causato da un motivo completamente diverso da quello spiegato nelle altre risposte.

La mia .. automethod:: mymodule.funcdirettiva in realtà avrebbe dovuto essere:

.. automethod:: mymodule::func`

Puoi usare la formattazione Pweave e noweb per generare i primi documenti che includono l'output del codice incorporato in essi. Fondamentalmente, scrivi il tuo primo file, con codice Python incorporato in blocchi contrassegnati come questo:

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

e Pweave eseguirà quei blocchi e li sostituirà con il loro output in un primo file risultante, che potrai poi usare con sphinx. Vedi l' esempio di Pweave reST per maggiori dettagli su come appare.