Мне нравится 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?
Сфинкс является главным образом инструментом для форматирования документов, записанных независимо из исходного кода, насколько я понимаю.
Для генерации документов API от docstrings Python ведущие инструменты являются pdoc и pydoctor. Вот сгенерированные документы API pydoctor для Скрученного и Базара.
Конечно, если Вы просто хотите взглянуть на docstrings, в то время как Вы работаете над материалом, существует "pydoc" инструмент командной строки и а также help()
функция, доступная в интерактивном интерпретаторе.
Входной фильтр doxypy позволяет Вам использовать в значительной степени все теги форматирования Doxygen в стандартном Python docstring формат. Я использую его для документирования большого смешанного C++ и платформы игрового приложения Python, и это работает хорошо.
Другой очень хороший инструмент документации является сфинксом. Это будет использоваться для предстоящей документации python 2.6 и используется django и большим количеством других проектов Python.
С веб-сайта сфинкса: