Warum verwendet CPython `sphinx.autodoc` nicht für die Standardbibliothek?

Question

Ich entwickle eine Python-Bibliothek und ich verwende sphinx.autodoc, um die Dokumentation zu generieren, da ich denke, dass dies ein guter Weg ist, sich nicht zu wiederholen und Dokumentation und Code in Übereinstimmung zu haben.

In einem Kommentar zu Emit reStructuredText from sphinx autodoc? habe ich gelernt, dass "der CPython-Dokument-Build-Prozess nicht Autodoc aktiviert hat (durch gezielte Wahl)".

Ich wundere mich, warum CPython es nicht verwendet und was sind die Nachteile der Verwendung von sphinx.autodoc?

Answer 1

Es ist meist eine Frage der Geschichte, aber auch eine Frage der persönlichen (und Projekt-) Präferenz. Heutzutage können Sie ziemlich brauchbare Dokumente erhalten, indem Sie sich hauptsächlich auf Docstrings verlassen und dann möglicherweise zusätzliche Prosa um sie herum hinzufügen.

Die Dokumentation von CPython ist jedoch lange vor der Existenz von Sphinx (in der Tat schrieb Georg Brandl die ursprüngliche Version von Sphinx, um CPythons altes Dokumentationssystem zu ersetzen).

So werden die Docstrings und die Prosadokumentation aus Gründen der Politik immer noch separat gepflegt, ohne auf die Verwendung von autodoc angewiesen zu sein.

Wir auch nicht erlauben die Verwendung von reStuctedText Docstrings in der Standard-Bibliothek, die die Vorteile der Verwendung von Autodoc weiter reduziert. (Siehe Q 10 in dem PEP 287 Q & A: http://www.python.org/dev/peps/pep-0287/#questions-answers)

Schließlich Georg Brandl pointed out die CPython in einer etwas einzigartigen Position, die Sie müssen vorsichtig sein, um sicherzustellen, dass die Version der Standard-Bibliothek, die die Bereitstellung wird DocStrings, wenn Sphinx läuft, ist die gleiche, für die du die Dokumentation erstellst. Es wäre viel zu einfach, versehentlich die falsche Version einzufügen und eine starke Abhängigkeit zwischen einem funktionierenden Python-Build und der Möglichkeit, die Dokumentation neu zu generieren, zu erzeugen.

Auf der Autodoc-Seite haben Sie das Problem, dass Sie beim Autodoc-basierten Dokumentieren die Docstring-Inhalte nicht ohne weiteres inline sehen können. Daher kann es schwierig sein, den Docstring-Text und die zusätzliche Prosa gut zu lesen zusammen. Dieses Problem kann durch eine automatische Browseraktualisierungslösung wie http://pymolurus.blogspot.com.au/2012/01/documentation-viewer-for-sphinx.html

gemildert werden. Autodoc hat auch ein Problem mit Abhängigkeiten von Neuerstellungen, da es nicht automatisch die richtigen Abhängigkeiten zu den Python-Quelldateien hinzufügt. Ich hatte definitiv Probleme, wo sich die Docstrings geändert haben, aber Sphinx hat die relevanten Ausgabedateien nicht neu generiert. (Ich glaube nicht, dass dies behoben wurde, aber wenn es in neueren Sphinx-Versionen gelöst wurde, lass es mich in den Kommentaren wissen und ich werde diese Beobachtung entfernen).

Während ich glaube, Sie besser Dokumentation erhalten und besser Docstrings von ihnen getrennt beibehalten (da die beiden Schreibweisen sind nicht genau die gleichen und roh Docstrings sind in der Regel leichter als Klartext zu lesen, als sie mit, wenn markiert sind reStructuredText), ein Ansatz, der mit hohen Kosten für zusätzlichen Wartungsaufwand und einem erhöhten Risiko von Inkonsistenzen einhergeht.

Dementsprechend ist für die meisten Dritt Python Projekte, mein Rat wäre, tatsächlich zu vermeiden Beispiel im Anschluss an die Standard-Bibliothek und statt:

• Verwendung reRestructuredText Docstrings (siehe PEP 287: http://www.python.org/dev/peps/pep-0287/)
• Verwendung apidoc/Autodoc
• zusätzliche Dokumentation Prosa hinzufügen um die automatisch eher eingebettet Docstrings als als Ersatz
• einen solchen autoupdating Ansatz verwenden wie oben zu sehen, verbunden, wie gut die Docstrings als Teil der Dokumentation lesen

Während es keine perfekte Lösung ist, diesen Ansatz tut sparen ziemlich viel duplizierten Aufwand sowohl Docstrings und Prosa Dokumentation bis in Einklang zu Datum.