Sphinx für PHP-Code-Dokumentation

Question

Sphinx ist eine Python-Bibliothek, um schöne Dokumentation aus einer Reihe von ReST-formatierten Textdateien zu generieren. Nicht das für die Volltextsuche verwendete Werkzeug

Ich bin mir auch voll bewusst, doxygen/phpdoc tools. Ich versuche herauszufinden, ob es eine Möglichkeit gibt, Sphinx zu verwenden, um PHP-Projekte zu dokumentieren. oder sogar andere Nicht-Python-Sprachen?

http://sphinx.pocoo.org/

Answer 1

Sphinx und ReST kann als generische Dokumentation Tools, in meiner Erfahrung verwendet werden. Es gibt nichts an Sphinx, das Sie verpflichtet, es nur für Python-basierte Projekte zu verwenden. Zum Beispiel habe ich in meiner Arbeit ein Benutzerhandbuch und eine XML-RPC-API-Referenz erstellt. In beiden Fällen hatte ich keine Verwendung für sphinx.ext.autodoc oder andere Python-spezifische Extras. Die Dokumentation wurde "von Hand" geschrieben, mit meist generischen ReST-Direktiven und nicht mit den Spezialdirektiven von Sphinx. Für das, was es wert ist, musste ich noch nicht eine benutzerdefinierte ReST-Direktive für Nicht-Python-Dokumentation erstellen.

Auch wenn Sie mit einem PHP-Projekt arbeiten, denke ich, dass Sie Sphinx nützlich finden werden. Zum Beispiel sind die meisten der von the module specific markup zur Verfügung gestellten Richtlinien tatsächlich ziemlich allgemein. Ich verstehe nicht, warum Sie diese Konstrukte nicht verwenden können oder wollen, um Zeug aus anderen Sprachen als Python zu dokumentieren. Ebenso macht Sphinx es sehr einfach zu show code examples in other languages. Es gibt sogar einen Konfigurationswert, um den Standard in jede Sprache zu ändern, die von Segmenten unterstützt wird (einschließlich PHP). Wenn Sie sich besonders ehrgeizig fühlen, könnten Sie sogar create a Sphinx extension etwas relevantes aus Ihrem PHP-Code herauspicken.

Alles, was gesagt wird, achten Sie darauf, die Zuschauer für Ihr Dokumentationsprojekt zu berücksichtigen. Während ich denke, dass Sphinx ein ausgezeichnetes Werkzeug ist und es für eine Vielzahl von Dokumentationsprojekten empfehlen würde, wenn Ihr Publikum etwas anderes erwartet, denken Sie daran. Wenn Sie beispielsweise ein Java-Projekt dokumentieren, erwartet ein Großteil Ihrer Zielgruppe Dokumente im Javadoc-Stil. Wenn Sie von dieser Erwartung abweichen, stellen Sie sicher, dass es nicht nur für Tritte ist (dh es gibt Ihnen bessere Dokumente, als Sie sonst bekommen würden) und bereit sein, (kurz) für das, was Sie anders gemacht haben, zu argumentieren (zB mit einem FAQ Antwort oder Einführung).

Schließlich ist jede Dokumentation besser als keine Dokumentation, unabhängig davon, mit welchem ​​Werkzeug sie erstellt wurde. Verwenden Sie ein beliebiges Tool, das Ihnen hilft, wenn es darum geht, etwas herauszubekommen und nicht.

Answer 2

veröffentlicht Gerade vor ein paar Tagen: http://mark-story.com/posts/view/sphinx-phpdomain-released

Answer 3

Die Lehre Projekt, ein ORM für PHP, Sphinx verwendet, um ihre Online-Dokumentation auf www.doctrine-project.org zu generieren. Sie verwenden ein angepasstes PHP-Fragment. Die Dokumentation ist auf Github unter https://github.com/doctrine/orm-documentation verfügbar. Es enthält die benutzerdefinierte PHP-Pygment-CSS-Datei.

Auch die python-pygments Paket kommt mit vielen pygment Stile, die Sie durch Ändern der pygments_style = Wert in Ihrer Sphinx conf.py Konfigurationsdatei ausprobieren können. Um zum Beispiel die pastie Hervorhebung sytle auszuprobieren, die Teil der Python-pygments ist, verwenden Sie

pygments_sytle = 'pastie' 

Answer 4

CakePHP Sphinx für seine neue Dokumentation verwendet, und ich schrieb die phpdomain für Sphinx. Zwar gibt es keine Möglichkeit, Ihre PHP-Doc-Blöcke automatisch in sphinx zu integrieren, aber ich denke immer noch, dass es eines der besseren Dokumentations-Authoring-Tools ist. Es ist großartig für mehr Dokumentation im Erzählstil.Aber mit der phpdomain können Sie auch API-Dokumente erstellen.

Answer 5

Soweit es mich betrifft, können Sie fast jede Syntax in Sphinx dokumentieren, sofern Sie sich nicht auf Sprachen beschränken, die von Autodoc unterstützt werden. Sie können schöne API-Referenzen mit Standard-Sphinx-Direktiven wie .. class, , .. function und anderen erstellen. Sie funktionieren perfekt neben dem Quellcode und erfordern keine automatische Generierung und Verknüpfung mit den Quellen.

Sie können auch allgemeine Ermahnungen mit einigen speziellen Klasse erstellen, die Sie später CSS Haken könnte:

.. admonition Title 
    :class: Ololo 

    This text could be formatted any way you want, using the ``Ololo`` tag. 

Es gibt auch Rollen sind (sie erlauben auch benutzerdefinierte Klassen) und andere Mittel der das Hinzufügen von Text mit einigen speziellen Formatierung, wenn Ihnen die ursprünglichen Anweisungen nicht ausreichen.

Wenn Sie beschließen, Ihre Dokumente asynchron aus dem Quellcode zu erstellen, stellen Sie sicher, dass Sie die Codeabdeckung und andere Code-bezogene Funktionen in Ihrem conf.py oder bei der Projektinitiierung deaktivieren.

PS: Sie können eine sehr gute Antwort auf Elemente mit benutzerdefinierten Klassen here sehen.

Answer 6

Wie Sie sehen gibt es eine Menge von Werkzeugen ist es, Ihnen dabei zu helfen, sonst, wenn Sie wirklich brauchen, es finden Sie unter:

https://blog.simpleigh.com/2012/08/php-documentation-and-sphinx