Software-Dokumentation mit Sphinx / Single-Source Multi-Channel Publishing

      Software-Dokumentation mit Sphinx / Single-Source Multi-Channel Publishing

      Praktisches Handbuch für technische Autoren und Self Publisher.



      Sphinx ist ein leistungsfähiges Werkzeug für die Dokumentation von Software. Ursprünglich geschrieben, um die Programmiersprache Python zu dokumentieren, entwickelte sich Sphinx in der Python-Community schnell zum Standard.

      Sphinx basiert auf einem einfachen Prinzip. Es generiert aus reStructuredText die gewünschten Zielformate wie HTML, PDF, EPUB, HTML Help, Qt Help, Devhelp, Texinfo oder Manpages. Durch seine Erweiterbarkeit und Flexibilität erobert sich Sphinx immer weitere Einsatzgebiete und empfiehlt sich als praktikable Single-Source Multi-Channel Publishing-Lösung.

      Dieses Buch hilft Ihnen beim Einstieg in die Softwaredokumentation mit Sphinx und macht Sie Schritt für Schritt mit den umfangreichen Leistungsmerkmalen des Programms vertraut. Es bietet sowohl Einsteigern als auch fortgeschrittenen Benutzern ein praktisches Handbuch für die tägliche Arbeit.
      Wenn man jetzt nicht gerade Python-Code schreibt, sondern C, C++ oder Java, empfiehlt sich Javadoc zur Quellcode-Dokumentation (für C und C++ in Form von doxygen mit Javadoc-ähnlicher Syntax). Die Microsoft-Sprachen (Visual Basic, C# etc.) verwenden eine XML-ähnliche Quellcodedokumentations-Syntax. Freilich können aus diesen Dokumentationskommentaren dann automatisiert unterschiedliche Zielformate generiert werden, andere Texte wie Bücher jedoch nicht – und auch Sphinx mit reStructuredText ist als Quellformat eher weniger geeignet, da die automatisierte Verarbeitung in vielen Programmiersprachen und Tools logischerweise nicht vorgesehen ist (würde einen Parser erfordern). Immerhin kann man reStructuredText nach XML/XHTML/ODT konvertieren und damit dann richtige Automatisierung betreiben.

      Dieser Beitrag wurde bereits 1 mal editiert, zuletzt von „skreutzer“ ()

      Klar, wenn man Java-Code dokumentieren will, greift man zu einer anderen Software. Man kann mit Sphinx allerdings auch andere Sprachen dokumentieren, wie zum Beispiel C oder C++. Quellcode-Kommentare in Python sind in reStructuredText geschrieben. Sie können also nahtlos in die übrige Dokumentation übernommen werden.

      Für mich persönlich ist entscheidend, dass Sphinx PDF via LaTeX und EPUB generiert. Das sind für mich die wesentlichen Formate.

      Damit lassen sich dann Dokumentation für die drei Medien Online, Buch und E-Book erzeugen.
      hasecke.com/plone-benutzerhandbuch/4.3/

      Weitere Beispiele hier: readthedocs.org/
      Ich selbst schreibe ja auch ein bisschen (und natürlich frei lizenzierte) Software, um aus Quelldateien automatisiert HTML, PDF und EPUB (Medien Online, Buch und E-Book) zu generieren, wobei meine Tools in erster Linie XML-basiert sind, da XML für Maschinenlesbarkeit konzipiert ist und sich folglich vorzüglich für derartige Aufgaben eignet, zumal XML-Programmierbibliotheken für quasi jede Programmiersprache zur Verfügung stehen und eine Vielzahl an mächtigen XML-Verarbeitungswerkzeugen und -Mechanismen zum Einsatz gebracht werden können (darüber hinaus ist XML ebenfalls ein Plain-Text-Format). Ich verstehe gut, dass sich reStructuredText als Front-End für eher einfache Textauszeichnung eignet, wo diverse XML-Formate erstmal zu komplex scheinen mögen für jemanden, der sich damit noch nicht viel auseinandergesetzt hat. Normalerweise wird das XML aber vom technisch wenig versierten Nutzer eben durch entsprechende Front-Ends verborgen, um trotzdem auch komplexere Auszeichnung möglich zu machen, bis hin zu XML-Formatdefinitionen, die gar nichts mehr mit Text, sondern mit der Strukturierung von textuell erfassbaren Daten zu tun haben.

      Jetzt käme natürlich reStructuredText als Front-End für die automatisierte, XML-basierte Verarbeitung in Frage. Daher würde ich gern wissen, wie denn die HTML-/XML-Ausgabe von Sphinx aussieht, genauer: ob von Sphinx semantisch ausgezeichnet wird. Denn reStructuredText oder LaTeX will man wohl kaum an allen möglichen Stellen parsen müssen, außer man ist Sphinx oder LaTeX. Bei XML sieht das schon wieder ganz anders aus.

      Womöglich würde ich mir sogar Ihr Buch eventuell kaufen, wenn die Sphinx-HTML-/XML-Ausgabe semantisch brauchbar ist ;) Allerdings wäre dafür Voraussetzung, dass es frei lizenziert und frei von jedweder DRM-Beschädigung ist, da ich Sie keinesfalls für den Akt der künstlichen Verknappung auch noch belohnen werde. Gedruckte Bücher sind zunächst einmal davon ausgenommen, da erstens die Materialkosten von Haus aus eine unumgängliche physische Beschränkung bedeuten und andererseits für den reinen Vorgang des Lesens (Wissen lässt sich glücklicherweise frei verbreiten und kann auf keine Weise eingeschränkt werden) digitale Grundrechte in Verbindung mit den modernen Digitalisierungsmöglichkeiten von physischen Büchern nur bedingt durch rechtliche Restriktionen betroffen wären. In diesem konkreten Fall wäre der Umstand allerdings sehr bedenklich, wenn das Buch nicht frei lizenziert wäre, denn Sphinx selbst ist unter der BSD-Lizenz veröffentlicht. Unfreie Dokumentation zu freier Software ist wie keine Dokumentation und auch definitiv kein Beitrag zur Arbeit derer, welche die der Dokumentation zugrundeliegende Software geschaffen haben (wobei die BSD-Lizenzierung zugegebenermaßen eine gewisse Gleichgültigkeit gegenüber der eigenen Arbeit nahelegt). Zuletzt kommt es aber noch ein wenig auf den Inhalt an, ob dieser eher informativ oder unterhaltsam ausgerichtet ist, denn Werke ohne praktischem Nutzen richten logischerweise auch weniger Schaden an, wenn der Zugang zu ihnen künstlich verwehrt wird.

      Dieser Beitrag wurde bereits 2 mal editiert, zuletzt von „skreutzer“ ()