Кажется, что существует множество инструментов документации для Python. Еще один, с которым я столкнулся, - epydoc. Похоже, что Sphinx является стандартом де-факто, поскольку он использовался для создания официальных документов Python. Может кто-то, пожалуйста, разобраться в текущем состоянии инструментов документации Python для меня?
Какова связь между докутиками и сфинксом?
Ответ 1
epydoc и Sphinx разные типы инструментов.
Они те же, что и они:
- Оба используют ReST через docutils.
- Оба очень Pythonic в фокусе
- Оба могут создавать документацию HTML и PDF
Они различаются по своему фокусу.
- Epydoc ориентирован на документацию API (Developer). Вы получаете больше результатов быстрее с помощью Epydoc. Вы указываете его на свой исходный код и получаете что-то. Это то, что я хочу из инструментария документации API.
- Sphinx ориентирован на общую (пользовательскую) документацию. Хотя Sphinx действительно извлекает много информации из вашего исходного кода, вам нужно добавить немного больше. Sphinx может генерировать документацию по API, но это не так прямо, и IMO не делает так хорошо, как работа Epydoc. Я знаю, что некоторые не согласятся, потому что Sphinx выбран для Python. НО, это зависит от того, сколько работы вы хотите вложить в нее. Я люблю Sphinx для общей документации.
Таким образом, это зависит от того, сколько работы вы хотите поместить в нее и что вы документируете.
Ответ 2
Кажется, что Epydoc является, если не мертвым, по крайней мере, для фьордов.
Сфинкс с командой sphinx-apidoc и autodoc является наиболее популярным вариантом для документов API в настоящее время.
Хорошие примеры:
Sphinx поощряет более нарративный стиль, чем инструменты в форме javadoc, но, может быть, это хорошо?
Ответ 3
Недавно я изменил с Python2 на Python3 и обнаружил, что для пакета Python3 не существует пакета Epydoc. Таким образом, похоже, что Python3 четко ориентируется на использование документации Sphinx как API.