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