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/Makefile
wygenerować kod HTML dla ys_utils
i wszystkie inne moduły, które będę mieć.
źródło
conf.py
./app
,/docs
... ty może używaćsys.path.append(os.path.join(os.path.dirname(__name__), '..'))
, a następnie wykorzystywać.. automodule:: app
w swojej.rst
-file.Jeśli
__init__.py
jest umieszczony prawidłowoa 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.
źródło
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.
Powyżej znajduje się mój plik index.rst. stuff.rst znajduje się w tym samym katalogu, co on.
źródło
index.rst
w/docs/source
i/ys_utils
. Zgaduję, że to powinno być wdocs
wersji? Używam tylko domyślnegoindex.rst
pliku, który został utworzony za pomocąsphinx-quickstart
.sys.path
, więc autodoc nie może ich znaleźć. Te.rst
pliki znajdują.Otrzymałem ten sam błąd, ale był on spowodowany zupełnie innym powodem niż wyjaśniono w innych odpowiedziach.
Moja
.. automethod:: mymodule.func
dyrektywa powinna właściwie brzmieć:źródło
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:
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.
źródło