Software-Dokumentation mit Sphinx

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.

»ein rundum gelungenes Buch zu diesem Thema, welches sowohl eine gute Einführung bietet als auch später als Nachschlagewerk dienen kann.«

(Jochen Schnelle in ›freies Magazin‹ 112015)

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.

Software-Dokumentation mit Sphinx

Paperback (deutscher Preis EUR 24,51)
E-Book (deutscher Preis EUR 8,99)

Inhaltsverzeichnis

  • Vorwort
  • Einleitung
    • Danksagung
  • Installation
    • Installation mit einem Linux-Paketsystem
    • Installation unter Mac OS X mit MacPorts
    • Installation unter Windows
    • Installation in virtueller Python-Umgebung
  • Einrichtung der Dokumentation
    • sphinx-quickstart
    • Elemente eines Sphinx-Projekts
  • reStructuredText
    • Absätze
    • Zeichenweise Auszeichnung
    • Das Maskierungszeichen
    • Listen
    • Eingerückte Absätze
    • Fester Zeilenumbruch
    • Quelltext
    • Hyperlinks
    • Überschriften
    • Anweisungen
  • Aufbau und Gliederung
    • Kapitelnummerierung
    • Tiefe des Inhaltsverzeichnisses
    • Weitere Optionen
    • Reservierte Namen
    • Metadatenfelder
    • Einbindung von Dateien
  • Erstellung der Ausgabeformate
    • Optionen von sphinx-build
    • HTML
    • Druckfähiges PDF
    • E-Book
    • Die Make-Optionen
    • Inhalte für bestimmte Ausgabeformate
  • Darstellung von Code
  • Abbildungen
    • Optionen der figure-Anweisung
  • Tabellen
    • reStructuredText-Tabellen
    • CSV-Tabellen
    • Konfiguration von LaTeX-Tabellen
  • Verweise und wissenschaftlicher Apparat
    • Interne Verweise
    • Verweise auf andere Sphinx-Dokumentationen
    • Fußnoten
    • Literaturverweise
    • Sonstige Verweise
  • Einsatzgebiete
    • Indikatoren für Einsatzgebiete
    • Wahl des Einsatzgebietes
    • Python
    • Andere Programmiersprachen
    • reStructuredText
    • Für den allgemeinen Einsatz
    • Weitere Einsatzgebiete
  • Mathematische Formeln
    • Anzeige als PNG-Bilder
    • Anzeige mit Mathjax
  • Stichwortverzeichnis
    • Absatzweise Indizierung
    • Indizierung im Fließtext
  • Glossar
    • Mehrere Glossare
  • Sonstige Anweisungen
    • Tipps, Hinweise, Warnungen
    • Ersetzungen
    • HTML-Markup und LaTeX-Befehle direkt eingeben
    • Kommentare
    • Hinweise zu einzelnen Versionen
    • Lokales Inhaltsverzeichnis
    • Container
    • Informelle Überschrift
    • Thema
    • Randnotiz
    • Epigraph
    • Herausstellung
    • Seitenansprache
    • Andere Autoren
    • To-Do-Listen
    • Grammatik-Produktionen
  • Einbindung von Docstrings aus dem Quellcode
    • Anpassung des Suchpfads
    • Die autodoc-Anweisungen
    • Konfigurationsparameter
    • Automatische API-Dokumentation mit sphinx-apidoc
  • Code testen mit Doctest
  • Überprüfung der Vollständigkeit
  • Verweise auf dokumentierten Quellcode
    • Beispiel für Bitbucket
    • Beispiel für Github
  • Bedingte Inhalte
    • Eastern Egg
  • Graphen und Diagramme
    • Konfiguration
    • Vererbungsdiagramme
    • Sonstige Erweiterungen
  • Anpassung des Webdesigns
    • Optionen der eingebauten Themes
    • Neue Themes installieren
  • Mehrsprachige Dokumentation
    • Gettext
    • Installation der notwendigen Software
    • Der Übersetzungsprozess
    • Konfiguration
  • Buch- und E-Book-Produktion
    • Buchformate
    • Kopf- und Fußzeilen
    • Einstellungen für EPUB-Ausgabe
    • Validierung der EPUB-Dateien
    • Versionsverwaltung
  • Konfiguration
    • Funktionsweise der Konfigurationsdatei
    • Abschnitte der Konfigurationsdatei
    • Die Konfigurationsparameter
    • Verwendung mehrerer Konfigurationsdateien
  • Glossar

  • Stichwortverzeichnis

  • Modulindex