Мне нравится 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 в стандартном формате docstring Python. Я использую его для документирования большой смешанной платформы приложений для С++ и Python, и она хорошо работает.
Sphinx - это в основном инструмент для форматирования документов, написанных независимо от исходного кода, как я понимаю.
Для создания документов API из docstrings из Python ведущими инструментами являются pdoc и pydoctor. Здесь pydoctor генерирует API-документы для Twisted и Bazaar.
Конечно, если вы просто хотите взглянуть на docstrings во время работы над материалом, там pydoc ", а также функцию help(), доступную в интерактивном интерпретаторе.
В итоге у вас есть только два варианта:
Вы создаете свой контент с помощью Doxygen или создаете свой контент с помощью Sphinx *.
Doxygen. Это не инструмент выбора для большинства проектов Python. Но если вам нужно иметь дело с другими связанными проектами, написанными на C или С++, это может иметь смысл. Для этого вы можете улучшить интеграцию между Doxygen и Python, используя doxypypy.
Sphinx: инструмент defacto для документирования проекта Python. У вас есть три варианта: ручной, полуавтоматический (генерация заглушки) и полностью автоматический (Doxygen like).
autosummary_generate. Вам потребуется настроить страницу с автозаполнениями, а затем вручную отредактировать страницы. У вас есть варианты, но мой опыт в этом подходе заключается в том, что он требует слишком большой конфигурации, и в конце даже после создания новых шаблонов я обнаружил ошибки и невозможность точно определить, что было открыто как открытый API, а что нет. Мое мнение, что этот инструмент хорош для генерации заглушек, который потребует ручного редактирования, и ничего более. Как ярлык, чтобы закончить в ручном режиме.Есть и другие варианты:
Другим очень хорошим инструментом документации является sphinx. Он будет использоваться для предстоящей python 2.6 документации и используется django и множество других проектов python.
С веб-сайта сфинкса: