Ошибка sphinx-build - autodoc не может импортировать / найти модуль

Question 1

Я пытаюсь начать работать со Sphinx, но у меня постоянные проблемы.

Команда: docs/sphinx-quickstart

Отвечаю на все вопросы и все работает нормально.

Команда: docs/ls

Все нормально выглядит. Результат:build Makefile source

Команда: sphinx-build -d build/doctrees source build/html

Вроде работает. Мне удалось открыть файл index.html и увидеть «оболочку» того, что я хочу.

Когда я пытаюсь поместить свой реальный исходный код в sourceпапку, у меня возникают проблемы.

Команда: sphinx-build -d build/doctrees ../ys_utils build/html

Результат:

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!

Я новичок в Sphinx и относительно новичок в подобной документации. Кто-нибудь может предложить какие-нибудь предложения?

Редактировать:

Я хотел бы иметь возможность использовать Makefile, чтобы справиться с этим. На данный момент у меня в проекте две папки.

nextgen/ls

docs ys_utils

Мне нужно nextgen/docs/Makefileсгенерировать HTML для ys_utilsвсех остальных модулей, которые мне понадобятся .

Question 2

Autodoc не может найти ваши модули, потому что их нет в sys.path .

Вы должны указать путь к вашим модулям в sys.pathфайле conf.py. Посмотрите на верхнюю часть вашего conf.py(сразу после импорта sys), естьsys.path.insert() утверждение, которое вы можете адаптировать.

Кстати: вы можете использовать Makefileсозданный Sphinx для создания своей документации. Просто позвони

make

чтобы увидеть варианты.

Если что-то пошло не так, прежде чем попробовать:

make clean

перед запуском make html.

Question 3

Похоже, os.path.append()это работает нормально для людей, но если вы следуете conf.pyшаблону, вы должны вставить путь к модулю перед sys.pathиспользованием os.path.insert(0, ...)и просто добавить дополнительный.

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

Если вы настроили свой sphinxпроект , чтобы использовать отдельные buildи sourceкаталоги, этот вызов должен быть вместо этого:

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

Question 4

в conf.py

просто добавьте путь к папке вашего проекта.

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

Question 5

Если

корневой путь модуля правильно установлен в conf.py
__init__.py размещен правильно
первый синтаксис правильный

и ваш автодок все еще не может найти модули ...

Это может быть связано с тем, что зависимости этих модулей не удовлетворяются в вашей среде python. Вам нужно будет проверить, все ли операторы импорта работают в модулях.

Question 6

Кажется, я сделал это в первый раз, когда попытался добавить файл в токтри. Думаю, это потому, что я пропустил пустую строку между строкой: maxdepth и именем файла.

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

Выше мой файл index.rst. stuff.rst находится в том же каталоге, что и он.

Question 7

Я получил ту же ошибку, но она была вызвана совершенно другой причиной, чем объяснено в других ответах.

Моя .. automethod:: mymodule.funcдиректива на самом деле должна была быть:

.. automethod:: mymodule::func`

Question 8

Вы можете использовать форматирование Pweave и noweb для создания первых документов, включающих вывод встроенного в них кода. По сути, вы пишете свой первый файл с кодом Python, встроенным в отмеченные фрагменты, например:

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

и Pweave выполнит эти блоки и заменит их выводом в результирующем первом файле, который затем можно будет использовать со sphinx. См. Пример Pweave reST для получения более подробной информации о том, как это выглядит.