dokumentation generator

[Sync32]

Hallo.
Ich suche ein nettes Dokumentationstool und bin auf dieses hier gestoßen:
http://sphinx.pocoo.org/

Kennt ihr sicherlich. Und da dachte ich mir, dass es eigentlich auch ein schönes Python-Einsteiger Projekt ist oder? Hab mir mal grob Gedanken gemacht und ich müsste theoretisch ja mit den Grundbasics auskommen.

Würde es wiefolgt realisieren:
- Man gibt einen Pfad ein
- Dort geht das Script alle .txt Dateien durch und jagt die durch den
- Parser (z.B. === test === -> Überschrift, [url] -> link etc.)
- und generiert daraus ein nette Dokumentation in html-Format + Inhaltsverzeichnis

Natürlich würde ich mir vor dem Beginn nochmal richtige Gedanken, Skizzen etc. machen. Aber ich wollte einfach mal vorweg fragen, ob jemand schon Erfahrung gemacht hat.
Ist das schweriger als man denkt oder ist das so nach mein Vorstellung gut machbar als Newbe

Bin für Tipps, Ideen und Vorschläge dankbar.

[DasIch]

Du kannst dir ja mal den Sphinx Code ansehen und einen Eindruck gewinnen aber ich kann mir nicht vorstellen dass ein Anfänger dazu in der Lage ist. Selbst die meisten fortgeschrittenen Programmierer schaffen es ja noch nichtmal einen brauchbaren Parser zu schreiben. Ich persönlich würde mir auf jedenfall nicht zu trauen einen restructured Text Parser zu schreiben.

[lunar]

@Sync32: Sphinx oder etwas, was dem auch nur entfernt nahekommt, als Anfänger aus dem Stegreif zu implementieren, ist aber schlicht und einfach unmöglich. Selbst ein erfahrener Programmierer braucht Monate, wenn nicht Jahre für ein solches Projekt, wie Du an der Geschichte von Sphinx sehen kannst.

Ein einfaches Programm aber, welches einfach nur Dokumente in HTML umwandelt, und dabei einen fertigen Parser für ein bestimmtes Format (z.B. Markdown) nutzt, sollte für einen Anfänger durchaus möglich sein. An einen eigenen Parser aber solltest Du Dich als Anfänger nicht wagen. Parsen ist tatsächlich nicht so einfach, wie es aussehen mag, und erfordert vor allem ein gewisses theoretisches Grundwissen.

[rads]

Ich kann meinen Vorrednern nur zupflichten, eine solche Aufgabe ist nicht zu unterschätzen.

In den letzten Wochen habe ich genau etwas vergleichbares gemacht

Datenbank-Werte -> (x)HTML -> Open Document File.

An sich funktioniert die Konvertierung ganz gut, aber spätestens bei "Grenzfällen", wie
was ist wenn der Benutzer Schlüsselwörter/zeichen eingibt, wird es unlustig.

Besonders das komplett eigenständige Entwickeln eines Parsers ist extrem viel Arbeit
um dann auch wirklich alle Funktionalitäten zu unterstützen. Abgesehen sollte natürlich
w3c abgesegnetes HTML dabei heraus kommen.

Wie Lunar sagte, nimm ein entsprechenes Tool, eine Bibliothek bzw. ein "Framework" dafür.
Ansonsten wirst du so schnell nicht mehr deines Lebens froh.

Glaub mir bitte

[Hyperion]

Datenbank-Werte -> (x)HTML -> Open Document File.

Nur so aus Interesse: Wieso der Umweg über XHTML?

[Defnull]

Datenbank-Werte -> (x)HTML -> Open Document File.

Nur so aus Interesse: Wieso der Umweg über XHTML?

Weil XHTML ein sauberes Zwischenformat ist und es bereits zahlreiche fertige XHTML->irgendwas Konverter gibt.

[Sync32]

Wenn ihr das so sagt, glaub ich das euch aber ich kann eure Beiträge noch nicht ganz nachvollziehen.

Was ist daran "schwer" ein kleinen Parser zu bauen? Ich brauch doch nur ein .txt File (welches bestimmte Synthax like Wikisynthax) beinhaltet, zeilenweise einlesen und entsprechend auswerten:

-> Html Kopfzeile einfügen
-> Zeile einlesen und prüfen:
Wenn du ein === findest, merk dir was zwischen den beiden === steht und schreib es als <h2> Text </h2> in die html. Datei
Wenn du ein [img] findest, merk dir den Pfad und mach daraus ein <img src="path" />
Wenn du ein ~~ findest, merk dir was zwischen den beiden ~~ steht und mach daraus ein <u>text </u> in der html. Datei
usw.

Und schon wird eine html Datei erstellt, die den Inhalt der .txt File formatiert darstellt.

Wo GENAU liegt da jetzt die Schwerigkeit ?
Klärt mich auf.

Denn erstell ich noch eine Übersicht.html, die alle erstellten html Datei verlinkt.

Trotzdem danke für euren Rat.

[rads]

Datenbank-Werte -> (x)HTML -> Open Document File.

Nur so aus Interesse: Wieso der Umweg über XHTML?

Zur Erklärung

1. Wenige Datenbankattribute halten HTML-Fragmente (durch ckeditor erzeugt)
2. Bei der Reporterstellung werden natürlich überschriften etc verwendet (Formatierungen)
3. Ich erst einen Report aufbauen und dann 1x das ODF File erstelle
4. Weil der Weg über odfpy, lxml nicht zielführend war und so ich OOo die Umwandlung machen lasse und
dort mit wenigen Zeilen html direkt zu odf wandeln kann (mit sehr guter qualität)

Was ist daran "schwer" ein kleinen Parser zu bauen?

Wir können dir nur eine Empfehlung ausspechen, da wir wahrscheinlich alle mal gedacht haben, "ach, das mach ich mal in ein paar stunden". Leider sind wir wohl auf die "schnauze gefallen" bzw. war der Aufwand wesentlich höher als erwartet.
Gerne kannst du es versuchen, wir sind sicherlich bzgl. der Lösung schon jetzt sehr gespannt und testen diese auch gerne für dich dann aus

[BlackJack]

@Sync32: Sphinx ist ja ein bisschen mehr als Du da beschreibst. Deine Beschreibung klingt eher nach einer agespeckten Variante von reStructuredText beziehungsweise nach einfachem Markup. Das kannst Du ja mal in Angriff nehmen. Wir versuchen Dir dann die Sonderfälle zu geben bei denen Dein Parser nicht funktioniert.

Mal so als Denkanstösse im Voraus: Ein Dokumentationstool sollte schon so mächtig sein, dass man es selbst damit dokumentieren kann. Also muss man irgendwie ausdrücken können, dass aus

=== Überschrift ===

eine Überschrift wird, und zwar ohne dass diese Zeile eine Überschrift wird, denn man möchte die Überschrift ja im Quelltextzustand zeigen, damit der Leser weiss wie er die schreiben muss.

Wie ist das mit Verschachtelungen!? Ist so etwas möglich ``=== [img="letter_A.png"]chtung ===``? Dann ist es nicht einfach nur die Zeile für eine Überschrift ersetzen, sondern man muss auch in der Überschrift wieder nach Markup schauen.

Letztendlich vielleicht doch ein interessantes Projekt für Anfänger, aber man sollte sich im klaren sein das man aller Wahrscheinlichkeit nach für den virtuellen Mülleimer programmiert. Ich denke jedenfalls nicht, dass die Welt *noch* ein Markup braucht.

[rads]

Wie ist das mit Verschachtelungen!? Ist so etwas möglich ``=== [img="letter_A.png"]chtung ===``? Dann ist es nicht einfach nur die Zeile für eine Überschrift ersetzen, sondern man muss auch in der Überschrift wieder nach Markup schauen.

Und spätestens dann sollten Begriff wie AST (Abstract syntax tree) und das Visitor Pattern bekannt sein.
Buchempfehlung. http://www.amazon.de/Compiler-Prinzipie ... 319&sr=8-1

[Barabbas]

Will man nicht - wenn überhaupt - einen Dokumentationsparser / -generator, der die Dokumentation aus dem Quelltext erstellt? Irgendwie habe ich den Eindruck, dass Sync32 ein Dokumentationsformat will, das völlig unabhängig vom Quellcode ist (ich kennen Sphinx nicht).

Keine Ahnung, ob das "verpönt" ist - aber teile der Python-Dokumentation scheinen auch so erstellt worden zu sein - und ganz im ernst: Warum sollte man darauf verzichten, etwa die Aufzählung der Parameter automatisiert erstellen zu lassen? Warum sollte ich mir doppelte Arbeit machen und einmal den QT dokumentieren und dann nochmal eine Dokumentation in HTML schreiben?

Wie gesagt - keine Ahnung, ob ich das Ansinnen des TE richtig verstehe - aber irgendwie scheint es mir nicht nur *schwer*, sondern auch überflüssig und allgemein der falsche Ansatz zu sein?

[DasIch]

Will man nicht - wenn überhaupt - einen Dokumentationsparser / -generator, der die Dokumentation aus dem Quelltext erstellt?

Nein, dass will man i.d.R. nicht. Zur Dokumentation gehören schliesslich auch noch Tutorials, Beispiele, Informationen zum Design, der Lizenz oder Installationsanweisungen. Django, Pylons, SQLAlchemy und docs.python.org nutzen alle Sphinx und solche Dokumentationen bekommt man nicht hin wenn man nur den Quelltext heranzieht. Desweiteren gibt es ja auch noch Module die in C geschrieben sind, die lassen sich auf die Weise nicht dokumentieren.

Außerdem unterstützt Sphinx neben Python auch noch C, C++, Javascript, restructured Text, Optionen für die Kommandozeile und von dritten gibt es noch Erlang und Ruby Unterstützung. Zum einen gibt es davon nicht in jedem Fall Quelltext den man auswerten könnte zum anderen würde das erfordern dass man Parser für alle unterstützten Formate braucht, der Aufwand ist viel zu hoch als dass das wirklich praktikabel ist. Ein weiteres Problem gerade bei Python ist dass selbst mit einen Parser der Aufwand enorm ist wenn man auch noch Deskriptoren und Klassenattribute/-methoden als solche dokumentieren will.

Sphinx hat allerdings eine "autodoc" Extension die Dokumentation für einzelne Module/Klassen/Funktionen erstellt durch eine Mischung aus parsen und ausführen von Code, damit lässt sich aber keine komplette Dokumentation generieren.

[lunar]

@Barabbas: Sphinx kann auch Dokumentation aus Docstrings extrahieren, und natürlich ist es sinnvoll, diese Möglichkeit zu nützen. Allerdings hat das natürlich Grenzen (z.B. bei Exemplarattributen oder in C implementierten Klassen oder Funktionen).

Außerdem muss gute Dokumentation mehr bieten als eine reine alphabetische Referenz alà Epydoc oder Javadoc. Schau Dir doch die Python-Dokumentation an. Dort finden sich zahlreiche Kapitel und Abschnitte, die man aus Quelltext gar nicht extrahieren kann (e.g. das Tutorial oder die What's new-Kapitel). Solche Abschnitte müssen manuell geschrieben werden, und zwar vorzugsweise in einem Format, dass einfach zu verstehen und zu schreiben, aber dennoch mächtig genug ist, und zudem in möglichst viele Anzeigeformate konvertiert werden kann. HTML erfüllt diese Anforderungen nicht. Es ist zwar mächtig, und kann noch einigermaßen gut konvertiert werden, aber von Hand ist es mühsam zu schreiben. Deswegen gibt es andere, einfachere Formate, die man anschließend in mehrere Anzeigeformate (z.B. HTML, PDF, usw.) konvertieren kann. Und genau das möchte der OP implementieren.

Eine gute Dokumentation ist eine Kombination aus manuell geschriebenem Freitext und generierter API-Referenz. Mit Sphinx funktioniert das wunderbar, weitaus besser als mit anderen Lösungen (z.B. der in C++ verbreiteten Kombination aus Docbook für Handbücher und doxygen für API-Referenz).

[Sync32]

Danke für die Antworten.

Es soll keine 1:1 Kopie von Spyinhx werden sondern zunächst einfach erstmal ein Parser, der .txt Dateien in ein schönen formatierten html-Dokument umwandelt. Das wäre erstmal mein erster Schritt.
Bis ich das fertig habe (einschließlich die Behandlung von "Sonderfällen:

Wie ist das mit Verschachtelungen!? Ist so etwas möglich ``=== [img="letter_A.png"]chtung ===``?

), bin ich - denke ich mal - erstmal ne ganze Zeit beschäftigt.

Als nächstes würde ich mich denn um Verlinkung/Verzweigung/Verknüpfung + Erstellen eines Inhaltverzeichnis (bei mehreren Dokumenten) kümmern.

Aber ich denke als erstes sollte ich eine fehlerfreie txt -> html Konvertierung versuchen
Wenn das klappt, geht es weiter

[Barabbas]

@DasIch & Lunar: Jo, danke für eure Einschätzung.

Ich selbst kenne nur doxygen - fand das aber im Vergleich zu anderen Dokumentations-Tools noch am besten. Für das nächste größere Projekt werde ich mir Sphinx auf alle Fälle mal ansehen, hört sich ja genau nach dem an, was man haben will .
Die bloßen Funktions-Referenzen (ellenlange Tabellen etc.) fand ich schon immer relativ anstrengend, wenn man als Entwickler eine bestimmte Schnittstelle / Möglichkeit sucht. Die Python-Dokumentation ist ja auch wirklich einfach mal top! Wobei ich z.B. die von PyGTK auch nicht sooOOoo schlecht finde - da weiß ich aber auch nicht, wie sie erstellt wurde. Ist jetzt vll. auch O.T.

Besten Gruß und vielen Dank,

brb