Sphinx für "normale" Dokumentation verwenden?

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.
Antworten
Marcos
User
Beiträge: 16
Registriert: Sonntag 4. Dezember 2011, 12:28

Hallo Zusammen!

Ich wollte mal wissen wie gut und sinnvoll es wäre, Sphinx für etwas anderes als Doku Python-Programme oder Programme allgemein zu verwenden.
Als Tool für die Erstellung von Doku allgemein, als Basisversion von der später auch PDFs, ePubs, Mobipocket etc. generiert wird.

Oder was würdet ihr da alternativ nehmen, von wo aus man mit möglichst einfachen Mitteln auf eine möglichst große Menge an Ausgabemöglichkeiten kommt.
Also am besten mit zahlreichen Formatvorlagen, damit man nicht für jedes Ausgabeformat erstmal komplet irgendwelche Stilvorlagen zusammenklöppeln muss.
DasIch
User
Beiträge: 2718
Registriert: Montag 19. Mai 2008, 04:21
Wohnort: Berlin

Sphinx wird von einigen auch für Webseiten und Bücher eingesetzt, insofern sollte "normale" Dokumentation (was auch immer damit gemeint ist) prinzipiell auch machbar sein.
Marcos
User
Beiträge: 16
Registriert: Sonntag 4. Dezember 2011, 12:28

Naja die Frage ist, was wäre die beste Alternative dafür..

Docbook fällt für mich aus weil ich absolut kein XML mag ;)
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Naja, eine Alternative wäre LaTeX. Das ist einigermaßen tauglich um PDFs zu generieren und vmtl. eBooks, dessen HTML-Ausgabe ist aber eher Grütze.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
lunar

@Marcos: Kommt auf die konkrete Dokumentation an. Sphinx ist zwar gut, aber eben auch nicht immer und für alles, insbesondere nicht unbedingt für API- und Projekt-Dokumentation für Projekte in anderen Sprachen, denn andere Sprachen haben meist ihre eigenen Standard-Dokumentationswerkzeuge… die im Übrigen durchaus auf XML basierend können (C# wäre ein populäres Beispiel. XML nicht zu mögen, ist eine Einstellung, die man sich als Entwickler so im Allgemeinen nur schwerlich leisten kann.
deets

lunar hat geschrieben: XML nicht zu mögen, ist eine Einstellung, die man sich als Entwickler so im Allgemeinen nur schwerlich leisten kann.
Im allgemeinen wohl kaum. Im Kontext von zu schreibenden Texten? Ganz bestimmt. XML ist gut als Austaschformat, weil wohldefiniert & mit maechtigen Parsern und Postprozessoren versehen.

Aber allein schon um Konfigurationen zu schreiben ist es aetzend, und erst recht grosse Texte. Nicht Umsonst gibt's Framemaker, oder JSON-basierte Konfigurationen.

XML gehoert zum Standardrepertoire, klar. Aber bitte nicht hand-erstellt....
BlackJack

Deshalb gibt es für DocBook ja XML-Editoren die das speziell unterstützen, damit man nicht so viel XML sehen muss. Ich habe es selbst noch nicht ausprobiert, aber mit Lyx kann man wohl auch DocBook schreiben (lassen).
deets

@BlackJack

Sage ich ja - FrameMaker zb. Oder ganz OpenOffice/LibreOffice... Nur ist mir dann auch egal, was dahinter steht.
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

DocBook existiert noch? Ich dachte das wäre im Zuge des XML-Hypes aufgetaucht und dann auch dementsprechend schnell verschwunden als Leute festgestellt haben, wie furchtbar DSSL, XML-FO zu nutzen sind. Aber vielleicht sehe ich das zu sehr aus der FOSS-Perspektive, keine Ahnung was Java-Enterprise-Shops machen.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
deets

Wir haben von Latex basierter Dokument-Erstellung auf FrameMaker gewechselt - weil's doch zu fummelig war, und Programierer brauchte fuer Anpassungen. Wirklich *geil* ist das aber auch nicht, der betreffende Kollege postet sogar auf Facebook darueber wie oft FM abschmiert...
lunar

@deets: Es ist eine Frage des Werkzeugs, wie gut oder schlecht man ein bestimmtes Format manuell editieren kann, und dementsprechend kann ich nicht umhin, Deine Abneigung gegen XML für größtenteils vorurteilsbehaftet zu halten.

Es käme schließlich niemand auf die Idee, LaTeX in einem einfachen Texteditor zu editieren, der keine Abkürzungen oder Tastenkombinationen für Schriftformatierung, Umgebungen und dergleichen bietet. XML aber scheint jeder daran zu messen, wie gut man es in einem einfachen Texteditor ohne schemabasierte Vervollständigung und dergleichen editieren kann.

Letztlich aber ist jedes Format nur so gut wie die zur Verfügung stehenden Werkzeuge, selbst vermeintlich einfache Textformate wie rest. Auch da möchte ich eigentlich einen Editor haben, der mir hilft, beispielsweise beim Markup für Überschriften.

Ein guter XML-Editor mit Vervollständigung, Strukturnavigation, intuitiven Eingabeverfahren (vgl. zen-coding) vereinfacht XML so weit, dass man es gut mit der Hand editieren kann. Natürlich gibt es in dieser Hinsicht trotzdem angenehmere Formate, einschließlich ReST oder Markdown, doch demgegenüber hat XML den bisher ungeschlagenen Vorteil, dass es in wirklich jeder Sprache mit Standardwerkzeugen verarbeitet werden kann. Es ist dagegen ein Ding der Unmöglichkeit, Rest in anderen Sprachen als Python zu verarbeiten, oder eine Markdown-Bibliothek aufzutreiben, die Dokumente als DOM repräsentiert und nicht automatisch gleich HTML daraus erzeugt.

@Leonidas: Docbook existiert durchaus noch, auch in freien Projekte. KDE und Gnome beispielsweise nutzen Docbook als Format für Handbücher und Benutzer-Dokumentation.
BlackJack

@lunar: Also ich schreibe LaTeX ohne spezielle Unterstützung vom Editor. Syntaxhighlighting und Autovervollständigung auf Basis des bereits vorhandenen Texts reichen mir aus. Das reicht mir bei XML auf Dauer nicht wirklich.
deets

@lunar

Vorurteile? Nach 15 Jahren XML erlaube ich mir Urteile. Die magst du nicht teilen. Aber Ahnungslosigkeit lasse ich mir nicht vorwerfen... ich habe mit Docbook gearbeitet, mit J2EE, struts, XML2Object-Mappern ala Castor und Co. Und bleibe dabei: XML ist fuer ein wohldefiniertes Austauschformat ok. Zum *schreiben*? Fuer lange Dokumente? Von Hand? Nein.

Zuerstmal ist deine Grundannahme falsch, niemand kaeme auf die Idee, Latex (oder andere Auszeichnungssprachen) "nur" mit einem Texteditor zu schreiben. Die Wikis dieser Erde sind das lebende Gegenbeispiel, und trotz aller Fortschritte bei WYSIWIG-Editoren.

Zum Zweiten gibt es fundamentale Unterschiede (im Kontext von *TEXT*-Auszeichnung) zwischen Latex/ReST und XML, bei dem ersteren sowas wie

\section{Mein Titel}

bzw.

Mein Titel
--------

nutzen. Und XML

<section><title>Mein Titel</title>

EEEEEWIG LANGER TEXT

</section>

Mit anderen Worten: die Notwendigkeit, schliessende Tags fuer geeignete Struktur zu benutzen, ist hoch nervend. Von unterschiedlichen Text-Repraesentationen in Text-Knoten vs. Attributen, den ganzen Diskussionen, wann Attribute oder wann nicht usw., mal abgesehen.

Natuerlich koennte man auch in XML einfach eingebettete Section-Tags haben. Aber dann ist das DOM auch nix mehr wert, weil nicht mehr struktur-definierend.

Und die von dir selbst zitierten Praeprozessoren ala ZEN-Coding stellen ja letzlich nichts anderes dar als den Versuch, aus einer anstrengend zu schreibenden Syntax etwas handhabbares zu machen, dass dann transformiert wird. Wo da jetzt der Unterschied zu ReST sein soll, welches mittels XSLT (Standardtool!) aus XHTML zum XML deiner Wahl wird, kann ich nicht ersehen.

Editoren wie FrameMaker oder OpenOffice nutzen XML als Dateiformat. Aber auch nicht wirklich mit menschenleslichen Ergebnissen. Das sind Serialisierungen von Datenstrukturen. Kann man mal mit arbeiten, aber *schreiben*?
lunar

@deets: Lies doch bitte meinen Beitrag. Ich habe Dir weder Ahnungslosigkeit vorgeworfen, noch behauptet, dass XML per se ein gutes Format ist – das ist es natürlich nicht im Bezug auf das Bearbeiten mit der Hand. Die exzessive Syntax von XML ist ein gewichtiger Nachteil bei der Verwendung von XML als Auszeichnungssprache, das habe ich nie bestritten.

Dieser Nachteil wird allerdings abgemildert oder – je nach Situation – gar ausgeglichen durch die verfügbaren Werkzeuge zur Bearbeitung von XML. Natürlich profitiert man von solchen Werkzeugen nicht, wenn man XML trotzdem in einem einfachen Texteditor bearbeiten, und in Situationen, in denen man keine Wahl hat, ist das natürlich ziemlich blöd.

Meine Annahme ist allerdings, dass man im Allgemeinen die freie Wahl des Werkzeugs hat, gerade beim Schreiben von Dokumentation, und mithin einen mächtigen XML-Editor oder gar einen speziellen Docbook-Editor nutzen kann, um Docbook zu schreiben. Dann ist Docbook vielleicht noch immer unangenehmer als ReST in einem einfachen Editor, aber doch bei weitem so unangenehm, als dass man gar nicht damit arbeiten könnte, so dass es sinnvoll ist, die Vor- und Nachteile von Docbook gegeneinander abzuwägen.

Man kann danach immer noch zur Einsicht gelangen, dass Docbook nicht geeignet ist, aber dann hoffentlich mit besseren Argument als „ich mag XML nicht“ oder dem pauschalen Verweis auf die syntaktisches Exzessivität von XML, sondern mindestens mit dem ausgewogenen Urteil, dass die Vorteile von XML die aufwendige Syntax von XML in der speziellen Situation auch unter Berücksichtigung der verfügbaren XML-Werkzeuge nicht aufwiegen.

Anbei bemerkt geht die Behauptung, man könne auch ReST über XHTML in XML umwandeln, am Problem vorbei, weil man so nur den bereits verarbeiteten Dokumentbaum in XML umwandelt, nicht aber den ursprünglichen Baum des ReST-Dokuments selbst.

@BlackJack: Eben weil Syntaxhervorhebung und einfache Vervollständigung bei XML nicht reicht, nimmt man für XML doch Editoren, die mehr können, wie eben schemabasierte Vervollständigung, automatisches Einfügen von Tags, usw.

Den impliziten Vorwurf, XML wäre schlecht, weil ein einfacher Editor eben nicht reicht, finde ich ziemlich absurd. Das ist doch wie Python vorzuwerfen, dass man es nicht mit Notepad editieren könne, sondern mindestens einen Editor braucht, der automatische Einrückung beherrscht, oder – um den Vergleich auf die Spitze zu treiben – dem Nagel vorzuwerfen, dass man ihn nicht mit der Säge in die Wand bekommt :)

Ich persönlich nehme deswegen einen Hammer für Nägel, und einen XML-Editor für XML :)
BlackJack

@lunar: Natürlich kann ich einem Format „vorwerfen”, dass es sich mit einem einfachen Werkzeug, welches ich für ganz viele Aufgaben verwenden kann, nicht vernünftig bearbeiten lässt, während andere Formate für den selben Zweck sich damit besser bearbeiten lassen. Zumal ich bisher auch keinen freien XML-Editor gefunden habe, der wirklich schön benutzbar war.
lunar

@BlackJack: Dieser Vorwurf steht allerdings –wie Du selbst festgestellt hast – unter der Prämisse, dass beide Formate auch tatsächlich demselben Zweck dienen.

Docbook erfüllt denselben Zweck wie ReST allerdings nur insofern, wie auch Python im Allgemeinen denselben Zweck wie Java oder C# erfüllt. Beides sind Auszeichnungssprache für Dokumentation. Ob beide aber konkret gleichermaßen zweckdienlich sind, hängt eben von den konkreten Anforderungen ab. ReST ist beispielsweise alles andere als zweckdienlich, wenn man es mit Java verarbeiten muss, während das bei Docbook keine sonderlich große Herausforderung wäre.

Deswegen – ich habe das Gefühlt, ich wiederhole mich – sollte man die Entscheidung gegen ein XML-basiertes Format auf einer fundierteren Basis als persönlicher Abneigung treffen, denn es gibt eben im Allgemeinen genügend viele Situationen gibt, in denen man um Docbook (oder XML im Allgemeinen) nicht herumkommt, oder es sich als für die konkreten Erfordernisse eben als am zweckdienlichsten erweist. Das – und nichts anderes – ist Inhalt und Aussage meiner Beiträge.
BlackJack

@lunar: Der gemeinsame Zweck ist durch das Thema hier vorgegeben und lautet ganz allgemein Dokumentation schreiben. Mit dem Zusatz, dass verschiedene Formate wie HTML, E-Books, und etwas Druckbares hinten raus fällt. Und da kann man selbstverständlich eine auf Erfahrungen basierende „persönliche” Abneigung gegen XML-Formate als Grund anführen.

Es gibt auch Gründe PHP einzusetzen. Was die Sprache nicht besser macht.
jerch
User
Beiträge: 1669
Registriert: Mittwoch 4. März 2009, 14:19

Irgendwie ist die Diskussion sophistisch. Mit den richtigen Tools wird jedes Format händelbar, wie z.B. der Browser zeigt. Mit dem richtigen Editor/IDE wäre selbst Brainfuck zu bewältigen (oder XSLT :twisted: ). Das Openoffice im Hintergrund XML nutzt, interessiert außer die Developer niemanden. Das Tool funktioniert nach vorne gut genug im Dau-Sinne, dass jeder mehr oder weniger damit zu Rande kommt. Selbiges könnte man auch für Docbook erreichen. Für den Anwender ist doch eigentlich nur die Güte der Schnittstelle entscheidend.

Simples Bsp. aus Python - wer versucht schon, pickle-Dateien "von Hand" zu schreiben - die Schnittstelle macht, was sie verspricht, ergo geht man darüber. Niemand versucht, pickle auf Repräsentationsebene zu verstehen. pickle könnte genauso gut die Daten im XML-Format gleicher Mächtigkeit ablegen, einziger Unterschied wäre neben erhöhtem Verarbeitungsaufwand, dass Leute versuchen würden, dieses XML-Format zu verstehen. Und stöhnen - uff ist das kompliziert. Imho ist das die Krux von XML, es versucht, gerade noch menschenlesbar zu sein und dabei Maschinenlesbarkeit/Austauschbarkeit zu gewährleisten, was XML in Rohform (also ohne das "richtige" Tool) näher zur Maschine rückt als zum Anwender, der ein Problem umzusetzen hat und mit einer speziell auf das Problem zugeschnittenen Sprache in dessen Rohform vllt. eleganter zum Ziel kommt.

Was ist lesbarer:

Code: Alles auswählen

<header>Überschrift</header>
= Überschrift =
SCNR

NB: Auch wenn sich das vllt. wie XML-Promotion liest, bin ich selbst kein großer XML-Fan und greife gerne auf simplere Lösungen zurück (Bsp. JSON). Das ist aber eher den Tatsachen geschuldet, dass XML in der Regel sehr viel teurer in der Verarbeitung ist bzw. das entsprechende Tool für XML-Format xy fehlt. Den Standardisierungsansatz finde ich nach wie vor bestechend.
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

jerch hat geschrieben:Niemand versucht, pickle auf Repräsentationsebene zu verstehen.
Haha, falsch. SCNR, aber der Artikel als solches ist interessant und zeigt auf dass ein vergleichbares XML-Format eine Stacksprache definieren müsste. Vielleicht kann man auch XSLT soweit biegen da was vergleichbares rausfällt.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
jerch
User
Beiträge: 1669
Registriert: Mittwoch 4. März 2009, 14:19

Leonidas hat geschrieben:Haha, falsch. SCNR, aber der Artikel als solches ist interessant und zeigt auf dass ein vergleichbares XML-Format eine Stacksprache definieren müsste. Vielleicht kann man auch XSLT soweit biegen da was vergleichbares rausfällt.
Hehe, schönes Ding. Mit XSLT hat XML den Fuß in der Programmiersprachentür (turing-vollständig), daher sollte das möglich sein. Freiwillige vor für einen veregneten Samstag? :wink:
Antworten