Должны ли мы использовать Epydoc, Sphinx или что-то еще для документирования API Python?

Моя команда нуждается в инструменте для создания документации API для проекта Python. Ранее мы использовали Epydoc и были очень довольны этим, но проект кажется мертвым, и последняя версия даже не совместима с последними docutils релизов.

Кажется, у нас есть три варианта, которые вы рекомендуете?

1) Продолжайте использовать Epydoc. Это в значительной степени потребует от нас вилки проекта, чтобы сделать его совместимым с docutils. Необходимые изменения довольно тривиальны - до сих пор мы фиксировали Epydoc локально, но все это требует некоторой работы, и мы действительно не заинтересованы в поддержке Epydoc.

2) Перейдите на Sphinx. Это отличный инструмент для общей проектной документации, но я не уверен, что это правильный инструмент для создания документации API. На самом деле я помню, как раньше отмечал заметку на страницах проекта Sphinx, заявляя, что это не инструмент документации API, и вместо этого следует использовать Epydoc. Я больше не вижу такой заметки, поэтому ситуация изменилась. Мы использовали reStructuredText как с Epydoc, так и с нашей другой документацией, поэтому переход на Sphinx, вероятно, не будет слишком большой задачей.

3) Используйте что-то еще. Есть ли другой инструмент, который вы бы рекомендовали для документации API Python?

Ответ 1

Пока я не использовал его лично, это похоже на расширение Sphinx autosummary, которое вам может понадобиться. Он упоминает, что он может генерировать файлы-заглушки для расширения autodoc, по существу, автогенерируя api, хотя похоже, что он все еще требует некоторого ручного хранения, которого epydoc не сделал.

Проблема api-autogeneration в сторону, Sphinx - это, безусловно, путь - он предлагает огромную гибкость в создании документации и обладает очень мощными инструментами разметки api (расширение autodoc, домен языка python). Главное, что сделало мою компанию переключением наших внутренних документов с epydoc, заключалось в том, что epydoc заставляет вас иметь сверху вниз "древовидное" представление библиотеки, отсортированное по имени; в то время как Sphinx позволяет группировать разделы вашей библиотеки api более логичным образом, определяемым его семантикой... недостатком является то, что вы предоставляете эту структуру, даже если вы просто хотите использовать макет epydoc tree.

Ответ 2

Моя проблема с Sphinx заключалась в том, что она просто не работала как инструмент API-документации, в то время как Epydoc, а также Doxygen и Doxygen с [DoxyPy] [1] работают очень хорошо. Проблема с Sphinx заключается в том, что его autodoc-плагин пытается импортировать каждый модуль python. Если импорт не удался, например, потому что модуль ожидает, что переменная все еще не установлена, Sphinx терпит неудачу. Таким образом, autodoc-плагин от Sphinx, похоже, предназначен для импорта и проверки только модулей, которые могут работать автономно. Epydoc также пытается импортировать каждый модуль, но если это не удается, например, поскольку курсор базы данных еще не установлен, Epydoc все еще анализирует модуль и предоставляет разумную документацию. С помощью Epydoc вы можете даже отключить импорт модулей и позволить ему только анализировать.

Хотя Doxygen работал быстро и качественно, у него есть некоторые недостатки. Например, чтобы получить нумерованный список в документации, вам необходимо создать его с помощью -# перед каждым элементом исходного кода. При использовании Epydoc это делается путем нумерации элементов, уже находящихся в источнике, поэтому элементы списка нумеруются в souce AND в документации. Кроме того, Expydoc имеет гиперссылку на "источник" для каждого элемента в сгенерированной html-документации. Нажатие на "источник" показывает документированный источник, который может быть очень полезен. Doxygen не имеет этой функции.

Проблема с Epydoc может заключаться в том, что последний выпуск был более 3 лет назад. Единственной проблемой, с которой я столкнулся в Windows 7 (64 бит, проф., Но с 32-битным Python 2.7.2), были сообщения об ошибках при установке ( "не удалось написать ключ" ), которые были предотвращены при запуске установки в качестве администратора. Другие, более свежие пакеты проверяют, имеют ли они достаточные права и просят установить их из учетной записи администратора. Кроме того, я попытался использовать конфигурационный файл с Epydoc. Однако использование параметров командной строки с командным файлом (epydoc.cmd) работает хорошо.

Результат для меня: я буду использовать Epydoc для документации по коду моего проекта python и попробуйте Sphinx повторить попытку при написании руководства пользователя.

Ответ 3

Как насчет doxygen?

Ответ 4

Когда я рассмотрел epydoc и sphinx, которые, по-видимому, являются лучшими вариантами для проектов python, я пришел к выводу, что Sphinx выпустил гораздо более удобную документацию, но было труднее заставить его автоматически создавать документацию. Мы начали с пустого проекта, поэтому решили структурировать наши docstrings в соответствии с epydoc, а не использовать Sphinx, который, казалось, имел более крутую кривую обучения. Если у вас есть существующий продукт, вам придется потратить усилия либо на преобразование docstrings, либо на создание Sphinx. Я думаю, что Сфинкс даст вам приятный результат. Также я думаю, что если вы собираетесь писать больше документации, то Sphinx лучше подходит.

Ответ 5

Более новая альтернатива - pdoc, которая предназначена для замены ненаблюдаемого эпидока. А именно, это генератор документации API нулевой конфигурации.

Ответ 6

Самое замечательное в Sphinx заключается в том, что вместо создания уродливой непригодной несортированной "документации API" она позволяет свободно смешивать рукописный текст с автоматически извлеченным документом для всего модуля, класса или функции.

Ответ 7

Вы можете легко переключаться с Epydoc на Sphinx и наоборот, используя Pyment, преобразуя код (отдельный файл или проект) с патчами:

pyment yourcode.py # or project folder
# then apply the patch(s)

По умолчанию он преобразуется в формат Sphinx, но может конвертировать его в другие, используя параметр -o:

pyment -o javadoc youcode.py

Обратите внимание, что epydoc вдохновлен стилем javadoc и так называется в Pyment.