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

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

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

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

Спасибо!

4b9b3361

ОТВЕТЫ

Ответ 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-модули.