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

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



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

823   5  

5 ответов:

Это документально на сайте 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?

42  
2008-09-12 14:11:03

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

64  
2015-06-28 03:28:20

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

для создания API-документов из Python docstrings ведущими инструментами являются pdoc и pydoctor. Вот созданные PYDOCTOR API docs для витая и базар.

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

20  
2015-04-04 20:34:57

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

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

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

  2. Сфинкс инструмент ранее для документирования проекта на Python. У вас есть три варианта здесь: ручной, полуавтоматический (stub generation) и полностью автоматический (Doxygen like).

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

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

  • Дыши: это началось как очень хорошая идея, и имеет смысл, когда вы работаете с несколькими связанными проектами на других языках, которые используют Doxygen. Идея состоит в том, чтобы использовать вывод Doxygen XML и передать его в Sphinx для создания вашего API. Таким образом, вы можете сохранить всю доброту Doxygen и унифицировать систему документации в Sphinx. Потрясающе в теории. Теперь, на практике, последний раз, когда я проверял проект, он не был готов производство.
  • pydoctor*: очень конкретное. Генерирует свой собственный выход. Он имеет некоторую базовую интеграцию со Сфинксом и некоторые приятные функции.
13  
2016-02-13 10:43:04

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

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

  • форматы вывода: HTML (включая Windows HTML Help) и LaTeX, для печати PDF-версий
  • обширные перекрестные ссылки: семантическая разметка и автоматическая ссылки на функции, классы, термины глоссария и аналогичные части информации
  • иерархической структуры: простое определение дерева документов, с автоматическими ссылками на братьев и сестер, родителей и детей
  • автоматические индексы: общий индекс, а также индекс модуля
  • код: автоматическая подсветка с помощью пигментного маркера
  • расширения: автоматическая тестирование фрагментов кода, включение docstrings из модулей Python и многое другое
12  
2008-09-12 16:48:59

Comments

    Ничего не найдено.
Click here to cancel reply.