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

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

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

84
задан Mogsdad 16 January 2018 в 20:07
поделиться

4 ответа

Это документируется на 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?

55
ответ дан 24 November 2019 в 08:31
поделиться

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

Для генерации документов API от docstrings Python ведущие инструменты являются pdoc и pydoctor. Вот сгенерированные документы API pydoctor для Скрученного и Базара.

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

20
ответ дан 24 November 2019 в 08:31
поделиться

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

78
ответ дан 24 November 2019 в 08:31
поделиться

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

С веб-сайта сфинкса:

  • Выходные форматы: HTML (включая Windows HTML Help) и ЛАТЕКС, для печатаемых версий PDF
  • Обширные перекрестные ссылки: семантическая разметка и автоматические ссылки для функций, классов, выражений глоссария и подобных сведений
  • Иерархическая структура: легкое определение дерева документов, с автоматическими ссылками на одноуровневые элементы, родителей и детей
  • Автоматические индексы: общий индекс, а также индекс модуля
  • Обработка кода: автоматическое выделение с помощью маркера Pygments
  • Расширения: автоматическое тестирование фрагментов кода, включение docstrings от модулей Python, и больше
13
ответ дан 24 November 2019 в 08:31
поделиться
Другие вопросы по тегам:

Похожие вопросы: