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

Próbuję rozpocząć pracę ze Sphinxem i wydaje mi się, że mam nieustające problemy.

Komenda: docs/sphinx-quickstart

Odpowiadam na wszystkie pytania i wszystko działa dobrze.

Komenda: docs/ls

Wszystko wygląda normalnie. Wynik:build Makefile source

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

Wydaje się, że działa. Udało mi się otworzyć plik index.html i zobaczyć „powłokę” tego, czego szukam.

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

Komenda: 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 w Sphinx i stosunkowo nowym w tego rodzaju dokumentacji. Czy ktoś może zaproponować jakieś sugestie?

Edytować:

Chciałbym móc użyć Makefile do obsługi tego. Na razie mam dwa foldery w swoim projekcie.

nextgen/ls

docs ys_utils

Muszę nextgen/docs/Makefilewygenerować kod HTML dla ys_utilsi wszystkie inne moduły, które będę mieć.

Autodoc nie może znaleźć Twoich modułów, ponieważ ich nie ma sys.path.

Musisz uwzględnić ścieżkę do swoich modułów w pliku sys.pathin your conf.py. Spójrz na górę swojego conf.py(tuż po zaimportowaniu sys), jest sys.path.insert()oświadczenie, które możesz dostosować.

Przy okazji: możesz użyć Makefilestworzonego przez Sphinxa do stworzenia swojej dokumentacji. Zadzwoń

make

aby zobaczyć opcje.

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

make clean

przed uruchomieniem make html.

Wygląda na os.path.append()to, że działa dobrze dla ludzi, ale jeśli postępujesz zgodnie z conf.pyszablonem, wstawisz ścieżkę modułu na początek sys.pathużywania os.path.insert(0, ...)i po prostu dodasz dodatkowy.

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

Jeśli skonfigurowałeś sphinxprojekt do używania oddzielnych katalogów buildi sourcekatalogów, to wywołanie powinno wyglądać tak:

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

w conf.py

po prostu dodaj ścieżkę do folderu projektu.

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

Jeśli

1. ścieżka główna modułu jest poprawnie ustawiona w conf.py
2. __init__.py jest umieszczony prawidłowo
3. pierwsza składnia jest poprawna

a Twój autodoc nadal nie może znaleźć modułów ...

Może to być spowodowane tym, że zależności tych modułów nie są spełnione w twoim środowisku Pythona. Będziesz chciał sprawdzić, czy wszystkie instrukcje importu działają w modułach.

Myślę, że zrobiłem to po raz pierwszy, gdy próbowałem dodać plik do drzewa. Myślę, że to dlatego, że pominąłem pustą linię między wierszem: maxdepth 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.

Otrzymałem ten sam błąd, ale był on spowodowany zupełnie innym powodem niż wyjaśniono w innych odpowiedziach.

Moja .. automethod:: mymodule.funcdyrektywa powinna właściwie brzmieć:

.. automethod:: mymodule::func`

Możesz użyć formatowania Pweave i noweb, aby wygenerować pierwsze dokumenty zawierające wynik osadzonego w nich kodu. Zasadniczo piszesz swój pierwszy plik z kodem Pythona osadzonym w oznaczonych fragmentach, takich jak ten:

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

a Pweave wykona te fragmenty i zastąpi je ich danymi wyjściowymi w wynikowym pierwszym pliku, którego możesz następnie użyć ze sphinx. Zobacz przykład Pweave reST, aby uzyskać więcej informacji o tym, jak to wygląda.