Was ist die Beziehung zwischen docutils und Sphinx?

StackOverflow https://stackoverflow.com/questions/2441078

Frage

Es scheint eine Vielzahl von Dokumentationstool für Python zu sein. Ein anderer, dass ich über den Weg gelaufen habe, ist epydoc. Es scheint, wie Sphinx der de-facto-Standard ist, weil es die offiziellen Python-Dokumente zu erzeugen, verwendet wird. Kann jemand bitte aussortieren den aktuellen Stand der Python-Dokumentation Tools für mich?

War es hilfreich?

Lösung

epydoc und Sphinx verschiedene Arten von Werkzeugen sind.

Es ist die gleiche, dass sie:

  • verwenden beide ReST über docutils .
  • Beide sind sehr Pythonic in ihrem Fokus
  • Beide können generieren HTML- und PDF-Dokumentation

Sie unterscheiden sich in ihrem Fokus.

  • Epydoc auf API (Developer) Dokumentation konzentriert. Sie erhalten mehr Ergebnisse schneller mit Epydoc. Sie richten Sie sie auf Ihren Quellcode und Sie etwas zu bekommen. Das ist, was ich von einer API-Dokumentations will.
  • Sphinx auf allgemeine (Benutzer) Dokumentation konzentriert. Während Sphinx eine Vielzahl von Informationen aus dem Quellcode tut ziehen müssen Sie mehr in sich ein wenig setzen. Sphinx kann API-Dokumentation erzeugen, aber es ist nicht so geradlinig, und IMO nicht so gut von einem Job als Epydoc macht. Ich weiß, dass einige nicht einverstanden, weil Sphinx für gewählt Python . ABER, es hängt davon ab, wie viel Arbeit Sie in sie setzen. Ich liebe Sphinx für allgemeine Dokumentation.

Es hängt also ab, wie viel Arbeit, die Sie wollen in sie gesetzt und was Sie dokumentieren.

Andere Tipps

Ich habe vor kurzem von Python2 zu Python3 geändert und festgestellt, dass es keine Epydoc Paket für Python3 war. So ist es mit Python3 scheint, ist es ein klarer Fokus auf Sphinx als API-Dokumentation verwendet wird.

Es scheint, wie Epydoc ist, wenn nicht tot, zumindest für die Fjorde sehnt.

Sphynx mit dem Sphinx-apidoc Befehl und die Autodoc Erweiterung sieht zu diesem Zeitpunkt die beliebteste Option für API-Dokumentation sein.

Gute Beispiele hierfür sind:

Siehe auch: Sollten wir epydoc, Sphinx oder etwas anderes für die Dokumentation von Python-APIs? (SO5579198)

Sphinx fördert eine Erzählstil als Werkzeuge in der javadoc Form, aber vielleicht ist dies eine gute Sache?

Lizenziert unter: CC-BY-SA mit Zuschreibung
Nicht verbunden mit StackOverflow
scroll top