Как сгенерировать документацию Python с помощью Sphinx с нулевой конфигурацией?

Мы не хотим поддерживать документацию, а также исходный код, который быстро развивается на данный момент, но Sphinx, похоже, требует разочаровывающего количества настроек и конфигурации. (Нам просто нужны некоторые базовые документы API.) Не существует ли какой-либо одной команды, которую вы можете запустить внутри проекта python, который будет просто перебирать все пакеты, модули, классы и функции, генерирующие документацию в виде HTML?

Sphinx-apidoc заносит материал в каталог, и после изменения conf.py, чтобы иметь наши пакеты в sys.path, мы можем запустить "make html", но в нем перечислены только пакеты и модули без документирования каких-либо классов или функций.

Ответы

Ответ 1

Инструмент sphinx-apidoc автоматически создаст заглушки для ваших модулей, что может быть тем, что вы хотите.

Инструкции

Убедитесь, что модуль autodoc включен во время конфигурации Sphinx.
```
extensions = ['sphinx.ext.autodoc']
```
внутри Sphinx conf.py должен сделать трюк.
Убедитесь, что conf.py соответственно отрегулирует sys.path (см. комментарии в строках 16-19 в файле).
```
sys.path.insert(0, os.path.abspath('/my/source/lives/here'))
```
Запустите sphinx-apidoc, чтобы сгенерировать скелеты.
```
sphinx-apidoc -o /my/docs/live/here /my/source/lives/here
```
Восстановите документы. Если все пойдет хорошо, вы не должны получать следующее предупреждение:

mymodule.rst: 4: ПРЕДУПРЕЖДЕНИЕ: autodoc не может импортировать/найти модуль 'mymodule'
Теперь должны быть заполнены ваши RST-модули.