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

Мне нравится Doxygen создавать документацию по коду C или PHP. У меня есть предстоящий проект Python, и я думаю, что помню, что у Python нет /* .. */комментариев, а также есть собственная функция самодокументирования, которая, похоже, является питоническим способом документирования.

Поскольку я знаком с Doxygen, как я могу использовать его для создания документации Python? Есть ли что-то конкретное, о чем мне нужно знать?

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

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

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

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

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

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

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

Следует отметить и другие варианты:

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

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

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

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

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

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

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