Sphinx-build fail - autodoc nie może zaimportować/znaleźć modułu

Question

Próbuję zacząć od Sphinx i wydaje się, że ma nieubłagane problemy.

Command: docs/sphinx-quickstart

odpowiem na wszystkie pytania i wszystko działa poprawnie.

Command: docs/ls

Wszystko wygląda normalnie. Rezultat: build Makefile source

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

wydaje się działać. Udało mi się otworzyć plik index.html i zobaczyć "powłokę" tego, czego potrzebuję.

Kiedy próbuję umieścić mój aktualny kod źródłowy jako folder source, napotykam problemy.

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

Wynik:

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! 

Jestem kompletnym nowicjuszem do Sfinksa i stosunkowo nowy w tego rodzaju dokumentacji. Czy ktoś może zaproponować jakieś sugestie?

Edit:

Chciałbym, aby móc użyć Makefile z tym poradzić. W tej chwili mam dwa foldery w moim projekcie.

nextgen/ls

docs ys_utils

muszę nextgen/docs/Makefile wygenerować kod HTML dla ys_utils i wszystkie inne moduły zamierzam mieć.

Answer 1

Myślę, że zrobiłem to za pierwszym razem, gdy próbowałem dodać plik do potwierdzenia. Myślę, że to dlatego, że zostawiłem pustą linię między: maxdepth line a nazwą pliku.

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

Powyżej znajduje się mój plik index.rst. stuff.rst znajduje się w tym samym katalogu co on.

Answer 2

Autodoc nie może znaleźć modułów, ponieważ nie są one w sys.path.

Musisz podać ścieżkę do swoich modułów w sys.path w swoim conf.py. Spójrz na górę swojego conf.py (zaraz po imporcie sys), istnieje instrukcja sys.path.insert(), którą możesz dostosować.

Nawiasem mówiąc: można użyć narzędzia Makefile stworzonego przez Sphinx w celu utworzenia dokumentacji. Wystarczy zadzwonić

make 

aby zobaczyć opcje.

Jeśli coś poszło nie tak, zanim spróbujesz:

make clean 

przed uruchomieniem make html.

Answer 3

w conf.py

tylko dodać ścieżkę do folderu projektu.

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

Answer 4

Sfinksa nie jest bardzo python3 kompatybilne z systemem __import__(module_name)Iimportlib.import_module(module_name) zarówno do pracy w moim tłumacza, ale nie w sfinks.

Próbowałem sprawdzanie gałąź master sfinks, zmieniłem tłumacza python3.4 w Makefile i dostał błędy na moduły, które zostały usunięte w serii 3.x. Można zobaczyć mój raport problem tutaj:

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

Answer 5

Można użyć Pweave i formatowanie temat Noweb wygenerować RST dokumenty, które zawierają wyjście kodu osadzonego w nich. Zasadniczo, można napisać plik rst, z kodem Pythona osadzonych w oznakowanych kawałki tak:

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

i Pweave będzie wykonywał te kawałki, i zastąpić je ich produkcji w wynikowym pliku rst, które można następnie wykorzystać przy sfinks. Zobacz Pweave reST example, aby dowiedzieć się więcej o tym, jak wygląda.

Answer 6

Próbowałem użyć autodoc do udokumentowania mojego kodu sfinks, ale pomijałby on jeden z moich plików, ponieważ nie zrobiłem klasy w tym pliku. Oto, jak plik wyglądał pierwotnie tak:

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

Ten plik nigdy nie zostanie pomyślnie udokumentowany przez sfinksa. Aby to być udokumentowane, musiałem wykonać następujące czynności:

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

Więc wydaje się, że Sfinks wymaga, aby wszystkie pliki owinąć się w klasie, aby je udokumentować. nadzieję, że pomoże, bo godzinami próbuje dowiedzieć się, dlaczego Sfinks nie został dokumentowania

Answer 7

Brzmi jak os.path.append() pracuje OK dla ludzi, ale jeśli się szablon conf.py, należy wstawić ścieżkę moduł do przodu sys.path użyciu os.path.insert(0, ...), i po prostu dodać dodatkowy .

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

Jeśli masz skonfigurowany projekt sphinx stosowanie oddzielnych bulid i source katalogów, że połączenie powinno być zamiast:

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