Блог

Я запускаю Sphinx в rst файле, содержащем automodule , но, похоже, он не оказывает никакого эффекта.

Вот подробности: у меня есть проект Python с файлом agent.py , содержащим Agent в нем класс. У меня также есть подкаталог apidoc с файлом agent.rst в нем (сгенерированный sphinx-apidoc ):

 agent module
============

.. automodule:: agent
   :members:
   :undoc-members:
   :show-inheritance:
 

Я запускаю sphinx sphinx-build -b html apidoc apidoc/_build с каталогом проекта в качестве текущего рабочего каталога.

Чтобы убедиться, что файлы Python найдены, я включил следующее в apidoc/conf.py :

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

Он работает без ошибок, но когда я открываю результирующий HTML-файл, он показывает только «модуль агента», и все пусто. Почему он не показывает класс Agent и его членов?

Обновление: первоначальная проблема, вероятно, была вызвана тем фактом, что я не включил sphinx.ext.autodoc conf.py . Однако теперь, когда я это сделал, я получаю предупреждения типа:

 WARNING: invalid signature for automodule ('My Project.agent')
WARNING: don't know which module to import for autodocumenting 'My Project.agent' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: autodoc: failed to import module 'agent'; the following exception was raised:
No module named 'agent'
 

Я попытаюсь ответить, применив «канонический» подход бок о бок с вашим случаем.

Обычный «подход к началу работы» следует за этими шагами:

1. создайте doc каталог в своем project каталоге (именно из этого каталога выполняются команды на следующих шагах).
2. sphinx-quickstart (выбираем отдельно source от build ).
3. sphinx-apidoc -o ./source ..
4. make html

Это дало бы следующую структуру:

 C:Project
|
|   agent.py
|   
|---docs
|   |   make.bat
|   |   Makefile
|   |   
|   |---build
|   |               
|   |---source
|       |   conf.py
|       |   agent.rst
|       |   index.rst
|       |   modules.rst
 

В вашем conf.py вы бы добавили (после шага 2):

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

и в index.rst вы бы связали modules.rst :

 Welcome to Project's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

 

Теперь сравните приведенное выше с тем, что у вас есть — из того, что вы поделили в своем вопросе:

 C:Project
|
|   agent.py
|   
|---apidoc
|   |   agent.rst
|   |   conf.py
|   |
|   |-- _build
 

Вы запустили:
sphinx-build -b html apidoc apidoc/_build

и в вашем conf.py :

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

Ваша ошибка stacktrace говорит, что не удалось найти модуль agent . Вероятно, это потому, что вы не опустились на 1 уровень ниже в своем conf.py (он указывает на путь с .rst , а не на путь с .py ), это должно сработать:
sys.path.insert(0, os.path.abspath('..')) . Кроме того, если вы не редактировали / не подключали свой вручную modules.rst index.rst , вы, скорее всего, увидите только этот модуль.

Возможно, вы захотите заметить подписи команд sphinx в игре:

 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>
 

 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
 

<sourcedir> относится к where .rst are и <MODULE_PATH> к where .py are . <OUTPUT_PATH> куда .rst помещаются и <outputdir> куда .html помещаются.

Пожалуйста, также обратите внимание, что вы упомянули: «каталог проекта в качестве текущего рабочего каталога». Я видел «рабочий каталог», упомянутый в потоках sphinx в stackoverflow, взаимозаменяемый как Project базовый каталог, так и docs каталог. Однако, если вы выполните поиск в документации Sphinx по «рабочему каталогу», вы не найдете упоминания об этом.

Наконец, есть преимущество в использовании структуры файлов / каталогов «подхода к началу работы». Это в основном «ставит вас на одну страницу» с большинством потоков в теге Sphinx, и таким образом облегчает умственную работу по сопоставлению обращений с различными структурами каталогов / файлов.

Надеюсь, это поможет.