Какая связь между документами и Сфинксом? - PullRequest
Новая
       22

Какая связь между документами и Сфинксом?

22 голосов
/ 14 марта 2010

Кажется, есть множество инструментов документации для Python. Еще один, с которым я столкнулся - это эпидок. Кажется, что Sphinx является стандартом де-факто, потому что он используется для генерации официальных документов Python. Может кто-нибудь разобраться в текущем состоянии инструментов документации Python для меня?

Ответы [ 3 ]

24 голосов
/ 14 марта 2010

epydoc и Sphinx - это разные типы инструментов.

Они одинаковы в том, что они:

  • Оба используют ReST через Documentstils .
  • Оба очень питоничны в своем фокусе
  • Оба могут генерировать HTML и PDF документацию

Они разные по своему фокусу.

  • Epydoc специализируется на документации API (разработчика). Вы получите больше результатов быстрее с Epydoc. Вы указываете это на свой исходный код, и вы получаете что-то. Это то, что я хочу от инструмента документации API.
  • Sphinx ориентирован на общую (пользовательскую) документацию. Хотя Sphinx действительно извлекает много информации из вашего исходного кода, вам нужно добавить в нее немного больше. Sphinx может генерировать документацию по API, но это не так просто, и IMO не так хорошо справляется с работой, как Epydoc. Я знаю, что некоторые не согласятся, потому что Сфинкс выбран для Python . НО, это зависит от того, сколько работы вы хотите вложить в это. Я люблю Сфинкса за общую документацию.

Так что это зависит от того, сколько работы вы хотите вложить в это и что вы документируете.

3 голосов
/ 06 февраля 2014

Я недавно перешел с Python2 на Python3 и обнаружил, что для Python3 не было пакета Epydoc. Похоже, что в Python3 особое внимание уделяется использованию Sphinx в качестве документации по API.

2 голосов
/ 08 мая 2013

Кажется, что Эпидок , если не мертв, по крайней мере тоскует по фьордам.

Sphynx с помощью команды sphinx-apidoc и расширения autodoc выглядит наиболее популярной опцией для документации API в настоящее время.

Хорошие примеры:

См .: Должны ли мы использовать Epydoc, Sphinx или что-то еще для документирования API-интерфейсов Python? (SO5579198)

Sphinx поощряет более повествовательный стиль, чем инструменты в шаблоне javadoc, но, может быть, это хорошо?

...