Das deutsche Python-Forum

Hallo,

hat jemand Erfahrungen mit dem Einsatz von Sphinx zur API-Dokumentation für C++-Quelltext? Mich würde interessieren, ob es eine Möglichkeit gibt, mit Sphinx automatisch aus C++-Quelltext Dokumentation zu extrahieren. Ich hab nichts dergleichen gefunden, was ohne Doxygen auskommt, fürchte also, dass dergleichen nicht existiert.

Ich bin nicht auf Sphinx fixiert, Hauptsache nicht Doxygen. Falls also jemand Erfahrungen mit anderen Doxygen-Alternativen hat, immer her damit

Danke,
lunar

Wie es aussieht, unterstützt die autodoc extension bisher nur Python: http://sphinx.pocoo.org/ext/autodoc.html. Es existiert allerdings eine C++-Domain, sodass du deinen C++-Quelltext mithilfe von Sphinx dokumentieren kannst, nur eben nicht durch automatische Analyse der C++-Kommentare.

@derdon: Danke, doch das hilft mir nicht. Der Quelltext muss kommentiert werden, und ich möchte die Dokumentation ja nicht zweimal schreiben.

Wie gesagt, es ist mir letztlich auch egal, welches Werkzeug ich nutze, solange es nur gerade nicht Doxygen ist. Sphinx wäre halt nur gut, weil ich mich damit als Python-Programmierer schon gut auskenne.

lunar hat geschrieben:Hauptsache nicht Doxygen

Was ist so schlimm daran? Ich nutze das für Objective-C und obwohl es unbestritten noch wesentlich besser ginge (für das nächste Projekt probiere ich mal appledoc aus) finde ich das jetzt nicht so schlimm. Man muss einmal durch diesen Wust an Optionen durchsteigen und danach ist es eigentlich wie JavaDoc.

Stefan

@sma: Javadoc ist schnell, Doxygen nicht. Im betroffenen Projekt dauert das Erzeugen der Dokumentation wesentlich länger als das Übersetzen des Quelltexts selbst. Mit komplexerem C++-Quelltext (e.g. viele abhängige Namen und oft mehrere Basisklassen) kommt Doxygen offenbar nicht allzu gut zurecht, und dabei ist das Projekt noch nicht mal groß (nur die Bibliotheken, von denen es abhängt).

Hinzu kommt, dass die Konfiguration ziemlich aufwendig ist, und die erzeugte Dokumentation auch nicht unbedingt einfach zugänglich ist.

Mal ne ganz doofe Frage: Was kann Sphinx denn mehr / besser als Doxygen? ... Also abgesehen von der geschwindigkeit jetzt.

Also wenn ihr jetzt abwegen solltet Sphinx oder Doxygen .. was würdet ihr nehmen?

@bennnil: Das kommt auf das Ziel an. Doxygen braucht IMHO Quelltext der dokumentiert werden soll. Man kann damit zwar theoretisch auch beliebige technische Dokumentation schreiben, aber das würde ich zu sehr als ”Missbrauch” des Werkzeugs ansehen. Wenn man also keinen Quelltext zu dokumentieren hat, würde ich Sphinx nehmen, wenn ich zwischen den beiden wählen muss.

Ansonsten ist die Frage ob die Sprache(n) der Quelltexte von Sphinx unterstützt werden und ob die Dokumentation eher Prosa oder eher Java-API-Doc-ähnlich sein sollen. Für Programmiersprachen, welche von Sphinx unterstützt werden, für die also eine Domain existiert, und falls die Dokumentation eher Prosa sein soll, dann Sphinx. Wenn API-Dokumentation im JavaDoc-Stil gefragt ist *und* es für die betreffende Programmiersprache keine bessere Alternative gibt, dann Doxygen. Für Python würde ich in dem Fall zum Beispiel Epydoc bevorzugen. Bei Java dagegen hatte IMHO Doxygen gegenüber dem dort mitgelieferten JavaDoc einige Vorzüge. Zumindest als ich es das letzte mal verwendet habe.

Im Ernstfall würde ich bei einer Programmiersprache, welche weder von Sphinx noch von Doxygen unterstützt wird, und für die es auch keine andere Alternative gibt, auch mal schauen wie aufwändig es wäre eine Domain für Sphinx zu implementieren.