помилка збірки сфінкса - autodoc не може імпортувати / знайти модуль

Я намагаюся розпочати роботу зі Сфінксом і, здається, маю невблаганні проблеми.

Команда: 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!

Я абсолютно новачок у Сфінксі і порівняно новий у цій документації. Хтось може запропонувати якісь пропозиції?

Редагувати:

Я хотів би мати можливість використовувати Makefile для вирішення цього питання. На даний момент у мене в проекті є дві папки.

nextgen/ls

docs ys_utils

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

Autodoc не може знайти ваші модулі, оскільки їх немає sys.path.

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

До речі: ви можете використовувати Makefileстворений Sphinx для створення вашої документації. Просто зателефонуйте

make

щоб побачити варіанти.

Якщо щось пішло не так, перш ніж спробувати:

make clean

перед бігом make html.

Здається, 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('../..'))

в conf.py

просто додайте шлях до папки проекту.

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

Якщо

1. кореневий шлях модуля правильно встановлений у conf.py
2. __init__.py розміщено правильно
3. перший синтаксис правильний

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

Це може бути через те, що залежності цих модулів не задовольняються у вашому середовищі python. Ви хочете перевірити, чи всі заяви про імпорт працюють у модулях.

Я думаю, що робив це вперше, коли я намагався додати файл до документа. Я думаю, це було тому, що я залишив порожній рядок між рядком: 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 знаходиться в тому самому каталозі, що і він.

Я отримав цю саму помилку, але вона була викликана зовсім іншою причиною, ніж пояснено в інших відповідях.

Моя .. automethod:: mymodule.funcдиректива насправді повинна була бути:

.. automethod:: mymodule::func`

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

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

і Pweave виконає ці фрагменти та замінить їх своїм результатом у результуючому першому файлі, який ви потім можете використовувати зі сфінксом. Дивіться приклад відпочинку Pweave для отримання більш детальної інформації про те, як це виглядає.