Как документировать код Python с помощью Doxygen

Ответ 1

Это задокументировано на веб-сайте Doxygen, но вкратце здесь:

Вы можете использовать doxygen для документирования вашего кода Python. Вы можете использовать синтаксис строки документации Python:

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

В этом случае комментарии будут извлечены doxygen, но вы не сможете использовать какие-либо специальные команды doxygen.

Или вы можете (аналогично языкам в стиле C в doxygen) удвоить маркер комментария (#) в первой строке перед элементом:

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

В этом случае вы можете использовать специальные команды doxygen. Конкретный режим вывода Python отсутствует, но вы, очевидно, можете улучшить результаты, установив для OPTMIZE_OUTPUT_JAVA значение YES.

Честно говоря, я немного удивлен этой разницей - кажется, что как только doxygen сможет обнаружить комментарии в блоках ## или "" ", большая часть работы будет выполнена, и вы сможете использовать специальные команды в в любом случае. Может быть, они ожидают, что люди, использующие "" ", будут придерживаться большей практики документации Pythonic, и это будет мешать специальным командам doxygen?

Ответ 2

Входной фильтр doxypy позволяет использовать почти все теги форматирования Doxygen в стандартном формате docstring Python. Я использую его для документирования большой смешанной платформы приложений для С++ и Python, и она хорошо работает.

Ответ 3

Sphinx - это в основном инструмент для форматирования документов, написанных независимо от исходного кода, как я понимаю.

Для создания документов API из docstrings из Python ведущими инструментами являются pdoc и pydoctor. Здесь pydoctor генерирует API-документы для Twisted и Bazaar.

Конечно, если вы просто хотите взглянуть на docstrings во время работы над материалом, там pydoc ", а также функцию help(), доступную в интерактивном интерпретаторе.

Ответ 4

В итоге у вас есть только два варианта:

Вы создаете свой контент с помощью Doxygen или создаете свой контент с помощью Sphinx *.

• Doxygen. Это не инструмент выбора для большинства проектов Python. Но если вам нужно иметь дело с другими связанными проектами, написанными на C или С++, это может иметь смысл. Для этого вы можете улучшить интеграцию между Doxygen и Python, используя doxypypy.

• Sphinx: инструмент defacto для документирования проекта Python. У вас есть три варианта: ручной, полуавтоматический (генерация заглушки) и полностью автоматический (Doxygen like).

  • В документации по API-интерфейсу API есть Sphinx autodoc. Это замечательно написать руководство пользователя со встроенными элементами, сгенерированными API.
  • Для полуавтоматического есть Sphinx autosummary. Вы можете либо настроить свою систему сборки для вызова sphinx-autogen, либо настроить свой Sphinx с помощью конфигурации autosummary_generate. Вам потребуется настроить страницу с автозаполнениями, а затем вручную отредактировать страницы. У вас есть варианты, но мой опыт в этом подходе заключается в том, что он требует слишком большой конфигурации, и в конце даже после создания новых шаблонов я обнаружил ошибки и невозможность точно определить, что было открыто как открытый API, а что нет. Мое мнение, что этот инструмент хорош для генерации заглушек, который потребует ручного редактирования, и ничего более. Как ярлык, чтобы закончить в ручном режиме.
  • Полностью автоматический. Это неоднократно критиковали, и долгое время у нас не было полностью полностью автоматического генератора API Python, интегрированного с Sphinx, до тех пор, пока не появится AutoAPI, который это новый ребенок в блоке. Это, безусловно, лучше всего подходит для автоматического создания API в Python (примечание: бесстыдная самореклама).

Есть и другие варианты:

• Breathe: это началось как очень хорошая идея и имеет смысл, когда вы работаете с несколькими связанными проектами на других языках, которые используют Doxygen, Идея состоит в том, чтобы использовать вывод Doxygen XML и передавать его Sphinx для создания вашего API. Таким образом, вы можете сохранить всю доброту Doxygen и унифицировать систему документации в Sphinx. Удивительно в теории. Теперь, на практике, в последний раз, когда я проверял проект, он не был готов к производству.
• pydoctor *: Очень важно. Производит собственный вывод. Он имеет базовую интеграцию с Sphinx и некоторые приятные функции.

Ответ 5

Другим очень хорошим инструментом документации является sphinx. Он будет использоваться для предстоящей python 2.6 документации и используется django и множество других проектов python.

С веб-сайта сфинкса:

• Форматы вывода: HTML (включая справку по Windows HTML) и LaTeX для печатаемых версий PDF
• Расширенные перекрестные ссылки: семантическая разметка и автоматические ссылки для функций, классов, терминов глоссария и аналогичных частей информации.
• Иерархическая структура: простое определение дерева документов с автоматическими связями с братьями и сестрами, родителями и детьми.
• Автоматические индексы: общий индекс, а также индекс модуля
• Обработка кода: автоматическое выделение с использованием яркости пигментов
• Расширения: автоматическое тестирование фрагментов кода, включение docstrings из модулей Python и многое другое