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

StackOverflow https://stackoverflow.com/questions/58622

Вопрос

Мне нравится 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?

Другие советы

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Выходные форматы:HTML (включая справку Windows HTML) и LaTeX для печати PDF-версий.
  • Обширные перекрестные ссылки:семантическая разметка и автоматические ссылки для функций, классов, терминов глоссария и аналогичной информации.
  • Иерархическая структура:простое определение дерева документов с автоматическими ссылками на братьев и сестер, родителей и детей
  • Автоматические индексы:общий индекс, а также индекс модуля
  • Обработка кода:автоматическое выделение с помощью маркера Pygments
  • Расширения:автоматическое тестирование фрагментов кода, включение строк документации из модулей Python и многое другое.
Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top