Как документировать код Python: Epydoc, doxygen, Sphinx, …?

Я не уверен, следует ли использовать Epydoc или doxygen для документирования моего кода на Python. В настоящее время я бы предпочел Epydoc, поскольку он специализируется на Python, и его синтаксис не слишком отличается от doxygen (который я использовал для документирования моего кода на C / C ++ до сих пор).

Любой аргумент против Epydoc или для использования doxygen?

  • http://epydoc.sourceforge.net/
  • http://www.doxygen.org/
  • http://sphinx.pocoo.org/

  • Могу ли я документировать код Python с помощью doxygen (и имеет ли он смысл)?
  • Как документировать типы параметров функции python?
  • 2 Solutions collect form web for “Как документировать код Python: Epydoc, doxygen, Sphinx, …?”

    Epydoc был классическим инструментом для создания документов. Тем не менее, каждый в последнее время движется к сфинксу.

    Вы должны использовать epydoc, или вы можете попробовать использовать sphinx. Документация Python сама по себе выполняется с помощью sphinx. Sphinx может предоставить вам больше контроля и лучшую документацию.

    В doxygen нет ничего плохого, но он дает большую пользу для программ c / c ++. Поскольку существуют специальные инструменты doc для кода python, они могут обеспечить вам лучший контроль над созданием документов.

    Я пробовал Sphinx, epydoc и doxygen для моего проекта python.

    Сфинкс не работал для меня, поскольку он зависит от возможности импорта каждого модуля. Хотя мой проект работает нормально, и Sphinx может найти свои модули, Sphinx не смог импортировать большинство модулей. Sphinx может быть полезен для общей документации и для создания руководства пользователя, но, по крайней мере, для документирования моего исходного кода бесполезно. Похоже, что модуль Sphinx должен иметь возможность работать автономно. Но в моем проекте первый модуль пытается подключиться к базе данных. Если соединение с базой данных завершается с ошибкой, она останавливается. Многие из других модулей ожидают, что курсор базы данных. Если соединение с базой данных не было установлено, они не могут быть импортированы и, таким образом, сбой Sphinx.

    Doxygen действительно работал хорошо. В сочетании с doxypy это еще лучше. Однако есть некоторые недостатки. Если вам нужен нумерованный список в исходном коде, вы не получите его в документации и наоборот. Более того, если вы читаете документацию, источник не отображается.

    Поэтому я попробовал Epydoc. Хотя Epydoc не обновлялся более 3 лет и, таким образом, был мертв, для меня он оказался на сегодняшний день лучшим инструментом для документирования кода python. Epydoc, так же как и Sphinx, пытается импортировать каждый модуль, НО если импорт завершается неудачно, он просто показывает сообщение об ошибке, а затем пытается проанализировать модуль, как делает doxygen. Документация, созданная Epydoc, хороша и имеет некоторые преимущества перед doxygen: 1. Источник, который документирован, можно сделать видимым одним щелчком мыши. 2. Нумерованные списки в docstring нумеруются и в документации.

    Установка Sphinx довольно сложна, если easy_install с подключением к Интернету не может быть использован. Это связано с тем, что Sphinx зависит от других пакетов. Doxygen можно установить так же просто, как и большинство программ, которые поставляются с установщиком с одним щелчком мыши. Но DoxyPy и может быть gaphviz также должен быть установлен. Expydoc тоже можно установить одним щелчком мыши, но в Windows 7 это нужно делать явно как admin, в то время как установщик Epydoc не проверяет, запущен ли он с достаточными правами. Получение первой полезной документации моего проекта было самым простым и быстрым с Epydoc. Наконец, Epydoc все еще можно рекомендовать как лучший инструмент для документирования проектов python. Sphinx может быть хорошим инструментом для создания пользовательской документации.

    Python - лучший язык программирования в мире.