Es scheint eine Fülle von Dokumentationswerkzeugen für Python zu geben. Eine andere, über die ich gestolpert bin, ist epydoc. Es scheint, als ob Sphinx der De-facto-Standard ist, weil es verwendet wird, um die offiziellen Python-Dokumente zu generieren. Kann jemand bitte den aktuellen Stand der Python-Dokumentationstools für mich aussortieren?Was ist die Beziehung zwischen Docutils und Sphinx?
epydoc und Sphinx sind verschiedene Arten von Werkzeugen.
Es sind die gleichen, dass sie:
Sie sind verschiedene Unterlagen erzeugen.
Es hängt also davon ab, wie viel Arbeit Sie hineinlegen wollen und was Sie dokumentieren.
Vielen Dank für die Erläuterung, was diese Tools gemeinsam haben (zB ihre Beziehung zu Docutils) und ihre Unterschiede. Was macht epydoc besser für die API-Dokumentation und Sphinx besser für die funktionale Dokumentation? Sie haben erwähnt, dass beide reST verwenden. Scheint so, als ob es viele Überschneidungen gibt. Ist es nur eine Frage der Bequemlichkeit? Auch die epydoc-Entwicklung scheint nicht sehr aktiv zu sein. Das letzte Commit war im Februar 2009, und die letzte Korrespondenz auf der Entwicklungsliste war im Mai 2009. – allyourcode
Nun, die einfache Antwort, warum man besser ist an einer Sache, die eine andere ist, ist die Art, wie sie entworfen wurden. Epydoc ist gemacht, um nur aus dem Code zu ziehen und Sphinx wird gemacht, um eine Menge seiner Dokumentation aus ReST-Dateien zu generieren, die Sie schreiben. Es gibt viele Überschneidungen. Sphinx ist das neue Kind auf dem Block. Ich habe Gerüchte gehört, dass es in .7 eine viel bessere Auto-Generation eingebaut haben wird. Ich habe großen Respekt vor Epydoc, aber Sphinx scheint momentan den ganzen Schwung zu haben. Ich mag es, weil es wie die python.org-Dokumentation aussieht UND ich denke, es sieht besser aus. –
Sphinx konzentriert sich nicht auf die allgemeine Benutzerdokumentation. Sphinx ist ein Werkzeug, das Ihnen hilft, eine vollständige und detaillierte Dokumentation zu schreiben, die Sie einfach nicht durch Verketten von Docstrings bereitstellen können. Sphinx wird auch sogenannte Domains mit 1.0 unterstützen, mit denen Sie ein in mehreren Sprachen geschriebenes Projekt dokumentieren können, zB eine Webapp in Python, Javascript und C. – DasIch
Es scheint wie Epydoc ist, wenn nicht tot, zumindest für die Fjorde sehnen.
Sphynx mit dem Befehl sphinx-apidoc und der Erweiterung autodoc scheint die derzeit beliebteste Option für API-Dokumente zu sein.
Gute Beispiele hierfür sind:
See: Should we use Epydoc, Sphinx or something else for documenting Python APIs? (SO5579198)
Sphinx fördert eine Erzählstil als Werkzeuge in der javadoc Form Aber vielleicht ist das eine gute Sache?
Ich habe kürzlich von Python2 zu Python3 gewechselt und festgestellt, dass es für Python3 kein Epydoc-Paket gab. So scheint es bei Python3 einen klaren Fokus auf die Verwendung von Sphinx als API-Dokumentation zu geben.
Aktueller Status? Was bedeutet das? Kannst du das weiter ausführen? Sphinx benötigt Dokutils; epydoc kann die gleiche RST-Notation verwenden. Was möchtest du wissen? Kannst du genauer sein? –
zB welche Tools haben eine starke Community-Unterstützung, aktive Entwicklung? Gibt es eine etablierte Lösung, oder gibt es viele, bei denen keine signifikant größere Follower haben? – allyourcode
Vielleicht sollten Sie den Titel dieser Frage bearbeiten. –