Как автоматически генерировать документацию API Python в PyCharm

Question

У меня есть проект Python в PyCharm, и я хотел бы автоматически генерировать документацию API (в виде HTML) из моего кода Python и docstrings.

Согласно this page, существует целый ряд инструментов, которые генерируют Python API документация:

• автореферата
• автодок
• PDoc
• PyDoc
• pydoctor
• Doxygen

страницы дополнительно отмечает, что следующие инструменты "Технологическая документация":

• Docutils
• Sphinx

PyCharm documentation says, которые могут быть использованы Docutils и Сфинкс, чтобы "произвести отформатированный API документацию" , Однако это кажется неправильным, поскольку their configuration indicates что эти инструменты обрабатывают только файлы *.rst, а не *.py файлов.

Мой вопрос заключается в следующем: могу ли я использовать функции PyCharm для DocUtils или Sphinx для создания документации API?

В противном случае могу ли я использовать любые функции PyCharm для этого?

В противном случае есть ли какие-либо инструменты для этого, которые хорошо интегрируются с PyCharm?

Answer 1

я наткнулся на эту проблему в короткие:

Мой вопрос заключается в следующем: Могу ли я использовать Docutils или функции сфинкс PyCharm для создания документации по API?

Нет, но вы можете использовать PyCharm для быстрого просмотра документации Ctrl + Q, и это будет хорошо отформатирован ссылки, таблицы и т.д.

В противном случае, я могу использовать любые возможности для PyCharm сделай это?

Не совсем, PyCharm может вставлять заглушку документации только для функций и методов, но не может сделать api-открытие, чтобы автоматически комментировать все, что он также не может создать.

В противном случае есть ли какие-либо инструменты для этого, которые хорошо интегрируются с PyCharm?

Да :) sphinx-apidoc Это инструмент, который автоматически создаст первые документы из вашего кода. Существует также менее известный autoapi

Вы просто указываете на корневую директорию, и вуаля может даже включать элементы без строки doc.Он просто создает простой первый документ с использованием синтаксиса automodule. После этого вы можете просто запустить задачу sphinx из PyCharm, и у вас есть документация вашего кода, вы можете даже использовать тему, например, sphinx_rtd_theme, чтобы она выглядела очень красиво.

Пример: sphinx-apidoc -o source/ ../ Предполагая, что вы создали папку DOC внутри вас проект, а затем cd doc и используется sphinx-quickstart вышеприведенная команда идет вверх в родительский каталог, чтобы открыть любой исходный файл и документировать их. Результат сохраняется в папке <project>/doc/source. Среди других файлов будет файл modules.rst, который вытаскивает все автоматически сгенерированные файлы вместе.

Тогда в вашем index.rst добавить строку в .. toctree:: ... source/modules