Я не уверен, следует ли использовать Epydoc или doxygen для документирования моего кода на Python. В настоящее время я бы предпочел Epydoc, поскольку он специализировался на Python, и его синтаксис не слишком отличается от doxygen (который я использовал для документирования моего кода на C/С++ до сих пор).
Любой аргумент против Epydoc или для использования doxygen?
Epydoc был классическим инструментом для создания документов. Однако каждый в последнее время переходит к сфинксу.
Вы должны использовать epydoc или можете попробовать использовать sphinx. Документация Python сама по себе выполняется с помощью sphinx. Sphinx может предоставить вам больше контроля и лучшую документацию.
В doxygen нет ничего плохого, но он дает большую пользу для программ 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 может быть хорошим инструментом для создания пользовательской документации.