Software-Dokumentation mit Sphinx (2. Auflage)

Praktisches Handbuch für technische Autoren und Self Publisher.

Software-Dokumentation mit Sphinx (2. Auflage)
Paperback: EUR 25,00
ISBN-10: 1793008779
ISBN-13: 978-1793008770
E-Book: EUR 8,99

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‹ 11/2015)

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.

Inhaltsverzeichnis

1 Vorwort
2 Vorwort der 1. Auflage
3 Einleitung
3.1 Danksagung
4 Installation
4.1 Installation von Python und dem Paketverwaltungssystem pip
4.2 Installation in virtueller Python-Umgebung
5 Einrichtung der Dokumentation
5.1 sphinx-quickstart
5.2 Elemente eines Sphinx-Projekts
6 reStructuredText
6.1 Absätze
6.2 Zeichenweise Auszeichnung
6.3 Das Maskierungszeichen
6.4 Listen
6.5 Eingerückte Absätze
6.6 Fester Zeilenumbruch
6.7 Quelltext
6.8 Hyperlinks
6.9 Überschriften
6.10 Anweisungen
7 Aufbau und Gliederung
7.1 Kapitelnummerierung
7.2 Tiefe des Inhaltsverzeichnisses
7.3 Globale Einbindung von Dokumenten
7.4 Reservierte Namen
7.5 Metadatenfelder
7.6 Einbindung von Dateien
8 Erstellung der Ausgabeformate
8.1 Optionen von sphinx-build
8.2 HTML
8.3 Druckfähiges PDF
8.4 E-Book
8.5 Die Make-Optionen
8.6 Inhalte für bestimmte Ausgabeformate
9 Darstellung von Code
10 Abbildungen
10.1 Optionen der figure-Anweisung
10.2 Bilder automatisch konvertieren
11 Tabellen
11.1 reStructuredText-Tabellen
11.2 CSV-Tabellen
11.3 Konfiguration von LaTeX-Tabellen
12 Verweise und wissenschaftlicher Apparat
12.1 Interne Verweise
12.2 Verweise auf andere Sphinx-Dokumentationen
12.3 Verweise auf dokumentierten Code
12.4 Verweis auf alles
12.5 Fußnoten
12.6 Literaturverweise
12.7 Sonstige Verweise
13 Einsatzgebiete
13.1 Indikatoren für Einsatzgebiete
13.2 Wahl des Einsatzgebietes
13.3 Python
13.4 Andere Programmiersprachen
13.5 reStructuredText
13.6 Für den allgemeinen Einsatz
13.7 Weitere Einsatzgebiete
14 Mathematische Formeln
14.1 Allgemeine Konfigurationsparameter für mathematische Formeln
14.2 Anzeige als PNG- oder SVG-Bilder
14.3 Anzeige mit Mathjax
15 Stichwortverzeichnis
15.1 Absatzweise Indizierung
15.2 Indizierung im Fließtext
16 Glossar
16.1 Mehrere Glossare
17 Sonstige Anweisungen
17.1 Tipps, Hinweise, Warnungen
17.2 Ersetzungen
17.3 HTML-Markup und LaTeX-Befehle direkt eingeben
17.4 Kommentare
17.5 Hinweise zu einzelnen Versionen
17.6 Lokales Inhaltsverzeichnis
17.7 Container
17.8 Informelle Überschrift
17.9 Thema
17.10 Randnotiz
17.11 Epigraph
17.12 Herausstellung
17.13 Seitenansprache
17.14 Andere Autoren
17.15 To-Do-Listen
17.16 Grammatik-Produktionen
18 Einbindung von Docstrings aus dem Quellcode
18.1 Anpassung des Suchpfads
18.2 Die autodoc-Anweisungen
18.3 Konfigurationsparameter
18.4 Automatische API-Dokumentation mit sphinx-apidoc
19 Code testen mit Doctest
19.1 Doctest-Konfiguration
20 Überprüfung der Vollständigkeit
20.1 Konfigurationsparameter
21 Verweise auf dokumentierten Quellcode
21.1 Beispiel für GitHub
22 Bedingte Inhalte
22.1 Easter Egg
23 Anpassung des Webdesigns
23.1 Optionen der eingebauten Themes
23.2 Neue Themes installieren
24 Mehrsprachige Dokumentation
24.1 Gettext
24.2 Installation der notwendigen Software
24.3 Der Übersetzungsprozess
24.4 Mehrsprachige Abbildungen
24.5 Übersetzung von Begriffen, die Sphinx automatisch einfügt
25 Deployment
25.1 HTML-Seiten auf den Webserver kopieren
25.2 Dokumentation auf dem Webserver erstellen
26 Buch- und E-Book-Produktion
26.1 Buchformate
26.2 Kopf- und Fußzeilen
26.3 Stiloptionen für Sphinx
26.4 Wahl der geeigneten LaTeX-Engine
26.5 Einstellungen für EPUB-Ausgabe
26.6 EPUB-Metadaten
26.7 Validierung der EPUB-Dateien
26.8 Versionsverwaltung
27 Konfiguration
27.1 Funktionsweise der Konfigurationsdatei
27.2 Die Konfigurationsparameter
27.3 Verwendung mehrerer Konfigurationsdateien
Optionen von sphinx-quickstart
Optionen von sphinx-intl
27.4 sphinx-intl update
27.5 sphinx-intl build
Glossar
Python-Modulindex
Stichwortverzeichnis