Вопрос по python-sphinx, python, documentation – Сбой sphinx-build - autodoc не может импортировать / найти модуль

68

Я пытаюсь начать работу со Сфинксом и, похоже, у меня постоянно возникают проблемы.

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

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

Команда:docs/ls

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

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

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

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

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

Результат:

<code>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!
</code>

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

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

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

nextgen/ls

docs ys_utils

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

Это выглядит как/home/ricomoss/workspace/nextgen/docs/build/doctrees/index.doctree не существует, и предполагается, что Это существует? Wayne Werner
Нет. Что я могу добавить (удалить?) Из Makefile, чтобы решить эту проблему? Rico

Ваш Ответ

7   ответов
-1

а, но он пропустил один из моих файлов, потому что я не создал класс в этом файле. Вот что файл изначально выглядел примерно так:

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

Этот файл никогда не будет успешно документирован sphinx. Чтобы это было задокументировано, мне нужно было сделать следующее:

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

Таким образом, кажется, что Sphinx требует, чтобы вы завернули все ваши файлы в класс, чтобы они были задокументированы. надеюсь, это поможет, потому что я часами пытался выяснить, почему Сфинкс не документировал

В случае, если это помогает объявить функции в файле index.rst для автоматического извлечения врачебных документов и т. Д... auto function:: a_function_name хорошо работает для меня
27

conf.py

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

sys.path.append('/home/workspace/myproj/myproj')
Жесткое кодирование пути - не лучшее, что вы можете сделать со своимconf.py.
Если у вас есть структура проекта, как/app, /docs... вы можете использоватьsys.path.append(os.path.join(os.path.dirname(__name__), '..')) а затем использовать.. automodule:: app в вашем.rst-файл.
Это лучшее решение! Благодарю. Также лучше добавить sys.path.append (& amp; ../& apos;), если ваша документация находится в docs /, так что если вы делаете коммит на git, тогда любой может запустить его локально.
19

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('../..'))
1

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

Куда это пойдет? я имеюindex.rst в/docs/source а также/ys_utils, Я предполагаю, что это должно быть вdocs версия? Я просто использую значение по умолчаниюindex.rst файл, который был создан сsphinx-quickstart. Rico
-1 так как из трассировки видно, что модули не вsys.path, так что autodoc не может их найти..rst файлы найдены.
-1

python3 совместимый, работает__import__(module_name) AND importlib.import_module(module_name) оба работают в моем переводчике, но не в сфинксе.

Я попытался проверить основную ветку sphinx, изменил мой интерпретатор на python3.4 вMakefile и получил ошибки на модулях, которые были удалены в серии 3.x. Вы можете увидеть мой отчет о проблеме здесь:

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

Извините, отрицательное голосование, потому что это а) не ответ на вопрос б) неверно в 2018 году, то есть Sphinx прекрасно работает на Python 3
68

sys.path.

Вы должны включить путь к своим модулям вsys.path в вашемconf.py. Look at the top of your conf.py (сразу после импортаsys), Eстьsys.path.insert() заявление, которое вы можете адаптировать.

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

make

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

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

make clean

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

0

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

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

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

Похожие вопросы