Как документировать код Python с doxygen

Question

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

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

Answer 1

Это documented on the doxygen website, но резюмировать здесь:

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

"""@package docstring 
Documentation for this module. 

More details. 
""" 

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

    More details. 
    """ 
    pass 

В этом случае комментарии будут извлечены с помощью Doxygen, но вы не сможете использовать любого из special doxygen commands.

Или вы можете (по аналогии с языками 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 может обнаружить комментарии в блоках ## или «" "блоки, большая часть работы будет выполнена, и вы сможете использовать специальные команды в любом случае. Может быть, они ожидают, что люди, использующие «" », будут придерживаться более практических методов написания документации Python и будут мешать специальным командам doxygen?

Answer 2

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

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

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

Answer 3

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

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

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

Answer 4

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

Answer 5

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

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

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

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

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

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

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