Автомодуль Сфинкса autodo c, по-видимому, не имеет никакого эффекта - PullRequest
Новая
       89

Автомодуль Сфинкса autodo c, по-видимому, не имеет никакого эффекта

2 голосов
/ 24 января 2020

Я запускаю 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 Ответ

2 голосов
/ 28 января 2020

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

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

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

В вашей трассировке стека ошибок сказано, что не удалось найти модуль agent. Вероятно, это связано с тем, что вы не поднялись на go 1 уровень в вашем conf.py (он указывает на путь с .rst, а не на путь с .py), это должно работать: sys.path.insert(0, os.path.abspath('..')). Кроме того, если вы не редактировали / не подключали modules.rst к своему index.rst, вы, скорее всего, увидите только этот модуль.
Вы можете обратить внимание на сигнатуры команд сфинкса во время игры: 
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>

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

<sourcedir> указывает, где находятся .rst, и <MODULE_PATH>, где .py есть. <OUTPUT_PATH> туда, где .rst, и <outputdir> туда, где .html.

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

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

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

...