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

Question

Sto provando a iniziare con Sphinx e sembra avere problemi incessanti.

Comando: docs/sphinx-quickstart

rispondo a tutte le domande e tutto funziona bene.

Comando: docs/ls

tutto sembra 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 ciò che sto volendo.

Quando provo a inserire il mio codice sorgente reale come cartella source, si verificano 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 novizio completo per Sfinge e relativamente nuovo a questo tipo di documentazione. Qualcuno può offrire alcuni suggerimenti?

Edit:

Mi piacerebbe essere in grado di utilizzare un Makefile per gestire questa situazione. A partire da ora ho due cartelle nel mio progetto.

nextgen/ls

docs ys_utils

Ho bisogno nextgen/docs/Makefile per generare il codice HTML per ys_utils e tutti gli altri moduli che ho intenzione di avere.

Answer 1

Penso di averlo fatto la prima volta che ho provato ad aggiungere un file al toctree. Penso che sia stato perché ho omesso la linea 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 è il mio file index.rst. stuff.rst risiede nella stessa directory di esso.

Answer 2

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

È necessario includere il percorso dei moduli nello sys.path nello conf.py. Guarda la parte superiore del tuo conf.py (subito dopo l'importazione di sys), c'è una dichiarazione sys.path.insert(), che puoi adattare.

A proposito: è possibile utilizzare lo Makefile creato da Sphinx per creare la documentazione. Basta chiamare

make 

per vedere le opzioni.

Se qualcosa è andato storto, prima prova:

make clean 

prima di eseguire make html.

Answer 3

in conf.py

basta aggiungere il percorso della cartella del progetto.

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

Answer 4

Sfinge non è molto python3 compatibile, in esecuzione __import__(module_name)Eimportlib.import_module(module_name) sia il lavoro nel mio interprete, ma non in sfinge.

Ho provato a controllare il ramo principale della sfinge, ho cambiato il mio interprete in python3.4 nello Makefile e ho ricevuto degli errori sui moduli rimossi nella serie 3.x. Si può vedere il mio rapporto problema qui:

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

Answer 5

È possibile utilizzare Pweave e la formattazione noweb per generare primi documenti che includono l'uscita del codice incorporato in loro. In sostanza, si scrive il file di prima, con il codice di pitone incastonato in blocchi segnalati come questo:

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

e Pweave eseguirà quei pezzi, e sostituirle con la loro produzione in un file prima risultante, che è quindi possibile utilizzare con sfinge. Vedi lo Pweave reST example per maggiori dettagli su come appare.

Answer 6

Ho provato a usare autodoc per documentare il mio codice sfinge, ma salta su uno dei miei file perché non ho creato una classe all'interno di quel file. Ecco come appariva inizialmente il file:

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

Questo file non sarebbe mai stato documentato con successo dalla sfinge. Per farlo essere documentato, ho dovuto effettuare le seguenti operazioni:

""" 
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() 

Così, sembra che Sfinge richiede di avvolgere tutti i file in una classe per farli documentati. Speranza che aiuta, perché ho passato ore a cercare di capire il motivo per cui non è stato Sfinge documentando

Answer 7

Sembra os.path.append() sta funzionando bene per la gente, ma se si segue il modello conf.py, si dovrebbe inserire il percorso del modulo verso la parte anteriore sys.path utilizzando os.path.insert(0, ...), e basta aggiungere un extra .

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

Se si dispone di impostare il progetto sphinx utilizzare separati bulid e source directory, la chiamata dovrebbe essere invece:

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