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

Это задокументировано на сайте 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?

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

С сайта сфинкса:

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

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

Для создания документации API из строк документации Python ведущими инструментами являются pdoc и пидоктор. Вот сгенерированные pydoctor документы API для Скрученный и Базар.

Конечно, если вы просто хотите взглянуть на строки документации, пока вы работаете над чем-то, есть инструмент командной строки «Pydoc», а также функция help(), доступная в интерактивном интерпретаторе.

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

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

Вы создаете свой контент, используя Doxygen, или вы создаете свой контент, используя Sphinx *.

1. Doxygen: это не лучший инструмент для большинства проектов Python. Но если вам приходится иметь дело с другими связанными проектами, написанными на C или C++, это может иметь смысл. Для этого вы можете улучшить интеграцию между Doxygen и Python с помощью доксипипия.

2. Сфинкс: инструмент де-факто для документирования проекта Python. Здесь у вас есть три варианта: ручной, полуавтоматический (создание заглушек) и полностью автоматический (как у Doxygen).

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

Есть и другие варианты, на которые стоит обратить внимание:

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