Wenn du dir nicht sicher bist, in welchem der anderen Foren du die Frage stellen sollst, dann bist du hier im Forum für allgemeine Fragen sicher richtig.
1. Aber das ist ja auch nichts, wo die Quelltextdateien mit entsprechenden Kommentaren versehen sind.
2. erübrigt sich, wenn man immer die Dokumentation an sich nochmal schreiben muss anstatt sie in die Quelltextdateien zu schreiben.
3. Zu einer guter Software gehört aber eben auch ein gut dokumentierter Quelltext.
4. Okay und wie macht sie das? Auf der Quickstart Seite komme ich bis Punkt 3. (http://michaeljones.github.com/breathe/quickstart.html)
Wo schreibe ich denn das rein was breath wissen will?
5. Naja wenn ich das richtig verstanden habe kann man mittels docsting die informationen aus dem Quelltext auslesen, wie man du einem Modul oder ähnlichem geben kann... Stimmt das etwa nicht?
1. Ich habe keine Ahnung ob und wenn ja wie viele der Projekte die als Beispiele verlinkt sind Gebrauch von der Erweiterung machen Docstrings aus den Quelltexten zu extrahieren. Hast Du alle durchgesehen? Andererseits sehe ich das auch nicht unbedingt als Hauptzweck von Sphinx.
2. Weiss ich jetzt nicht so ganz was Du damit sagen möchtest.
3. Man muss bei dokumentiertem Quelltext zwischen Kommentaren zum Quelltext selber und der API-Dokumentation unterscheiden. Letztere sollte bei guter Software zwar vorhanden sein, muss aber nicht zwingend *im* Quelltext stehen.
4. Die Punkte 1 bis 4 beziehen sich alle auf die ``conf.py`` von Sphinx. Bei Punkt 3 der Pfad muss zur XML-Ausgabe von Doxygen führen und der Projektname bei den Punkten 3 und 4 sollte gleich sein.
5. Docstrings werden als Attribut `__doc__` an die Objekte gebunden zu denen sie gehören. Und da kann man sie dann zur Laufzeit abfragen. Das macht zum Beispiel die `help()`-Funktion. Ausserdem gibt es Werkzeuge, die statische Dokumentation daraus erstellen. Zum Beispiel `pydoc` aus der Standardbibliothek oder `epydoc`. Es gibt noch ein paar andere Alternativen. Und Sphinx hat eine Erweiterung mit der man Dokumentation auf diese Art auslesen kann.
Docstrings selbst, also dass die Information zur Laufzeit auf den Objekten zur Verfügung steht, ist nicht so verbreitet bei Programmiersprachen, aber für viele gibt es Dokumentationskonventionen für Kommentare im Quelltext und Werkzeuge um daraus eine API-Dokumentation zu erstellen.
Danke erstmal für die Antworten.
Eine Frage habe ich noch ... zu Frage 4:
Wie schreibe ich das denn in die conf.py rein?
Der XML Ordner liegt in C:\Python27\testbreathe\source\_static\xml
Und das Projekt nennen wir jetzt einfach mal Testproject.
Wie müsste ich das denn nun in die Datei schreiben?
Die restlichen Punkte habe ich schon geschafft.
@bennnil: Das müsstest Du so in die Datei schreiben wie es in der Schnellstart-Anleitung beschrieben steht. Was hast Du denn rein geschrieben und was funktioniert nicht?
Potentielle Stolperfalle sind hier vielleicht Escape-Sequenzen in literalen Zeichenketten, also die Sonderbedeutung des Backslash (``\``). In der Dokumentation ist im Abschnitt String literals eine Tabelle. Aber grundsätzlich sollte man alle Backslashes entsprechend schützen und nicht nur die „gefährlichen” oder gleich ein „Raw”-Zeichenkettenliteral verwenden.
Du hast BJ falsch verstanden. Das Escapen wird nicht mittels ```` gemacht, sondern mit einem (weiteren) Backslash vor dem zu schützenden Zeichen. Bei Windows-Pfadangaben kannst du dir Raw-Strings angewöhnen. Die nehmen dir in der Hinsicht ein bißchen Arbeit ab. Beispiel:
irgendwie ändert das nichts ... könnte einer von euch mir das mal aufschreiben wie es sein müsste ? ich bekomme wieder die Fehlermeldung das breathe nicht importiert werden konnte. :/
@bennnil: Dann stimmt wahrscheinlich mit Punkt 1 aus der Schnellstart-Anleitung etwas nicht. Stimmt der Pfad denn? Gibt es dort ein Paket oder Modul mit dem Namen das importiert werden kann?
Okay danke euch beiden für die Hilfe. Habe es hinbekommen. Ich weiß nicht so ganz warum es jetzt funktioniert und vorher nicht aber anscheinend habe ich mich iwie verschrieben. Habe nochmal ein komplett neues Projekt erstellt und da nochmal alles neu in die Conf datei geschrieben.
Eine Frage habe ich noch ... allerdings eher eure Erfahrungen betreffend:
Würdet ihr Sphinx also Dokumentationstool für in C++ geschrieben Programme einsetzen. Es geht sowohl um eine Entwicklerdokumentation also auch eine Benutzerdokumentation.
Wenn ja, warum?
Wenn nein, warum nicht (alternative) ?
Es wäre sehr nett, wenn ihr euch nochmal die Mühe machen könntet mir diese Frage zu beantworten.
@bennnil: Ich würde keine in C++ geschriebenen Programme dokumentieren wollen.
Falls die Fragestellung auch für C gilt: Ja, würde ich verwenden. Gerade bei der Benutzerdokumentation finde ich reStructuredText eine angenehmere Variante als beispielsweise die Auszeichnungssprache von Doxygen. Doxygen würde ich nehmen falls eine reine API-Dokumentation im Java-Stil gefragt ist. Und auch als Ansatz falls das nicht mein Code ist, den ich da dokumentiere, denn auch ohne Dokumentationskommentare ist die Ausgabe von Doxygen inklusive verlinktem Quelltext, ganz gut geeignet um einen Überblick über ein Projekt zu bekommen.
Exception occurred:
File "C:\Python27\lib\xml\dom\expatbuilder.py", line 207, in parseFile
parser.Parse(buffer, 0)
ExpatError: not well-formed (invalid token): line 224, column 209
Und noch wichtiger: Was kann ich dagegen tun, dass breathe mich ärgert?
bennnil hat geschrieben:Okay ja das tut breathe auch. Aber was kann ich dagegen machen? Ich habe die Datei mit Doxygen erstellt und daran kann ich ja nicht viel ändern.
Heißt es jetzt, dass ich damit nicht weiterarbeiten kann?
Er Parser zeigt Dir doch die exakte Stelle an, an welcher der Fehler auftritt. Schau es Dir doch mal an. Evtl. kann man das ja leicht manuell fixen oder aber man erkennt ein grundsätzliches Problem (Encoding z.B.), an welchem man etwas ändern kann.
In welcher Datei muss ich denn da schauen? Der Doxygen Output besteht aus ner Menge XML Dateien. Und in der Index Xml gibt es die stelle nicht, wo angeblich der Fehler ist.
@bennnil: Ich würde einfach alle XML-Dateien mal auf Syntaxfehler überprüfen. Unter Linux bietet sich dafür ``xmllint`` an. Keine Ahnung was man unter Windows dafür am besten nimmt. Notfalls könntest Du auch ein kleines Python-Programm schreiben.
Es wäre nur ganz klasse, wenn mir vllt jemand von euch dabei helfen könnte, da ich mich überhaupt nicht mit Python auskenne Und natürlich arbeite ich unter Windows Also hilft mir der Tipp mit dem Linuxbefehl leider nicht :'(.
Ich glaube nicht, dass Dir jemand einen XML-Syntax-Checker bastelt... aber es wird da sicher auch etwas für Windows geben! Iirc gab es für notepad++ ein XML-Plugin, das das konnte.
Und natürlich arbeite ich unter Windows 
Also hilft mir der Tipp mit dem Linuxbefehl leider nicht :'(.