Sphinx-Toolchain
Sphinx-Toolchain#
Autor des Abschnitts: Sebastian Gabriel
Die Lösung für meine Anforderungen erregte 2017 meine Aufmerksamkeit in Form der .
Sphinx, bzw. die Sphinx-Toolchain, ist ein Dokumentationsgenerator und hat seine Wurzeln in der Python-Programmiersprachen-Community. Es wurde hauptsächlich zur Dokumentation von Python-Softwareprojekten verwendet. Seit seiner Einführung hat die Softwareentwickler-Community im Allgemeinen viel Aufmerksamkeit auf sich gezogen, sodass viele Projekte ihren Dokumentationsworkflow auf Sphinx umstellen. Eines der bekanntesten wäre das Linux-Kernel-Projekt, das 2016 seinen DocBook-basierten Workflow auf Sphinx migriert (beginnend mit dem Release-Zyklus 4.7) 1 .
Obwohl Sphinx sich im Bereich der technischen Dokumentation einen Namen gemacht hat, ist es auch ein leistungsstarkes Tool für allgemeine Publikationen. Was macht es so toll? Lassen Sie uns zunächst darüber sprechen, was Sphinx eigentlich ist:
Sphinx verwendet ein einfaches Textformat für den Textinhalt: Restructuredtext („RST“, 2). RST selbst ist ein gut lesbares Format, das erweitert werden kann, um Querverweise, Fußnoten und semantische Markups zu ermöglichen (dies wirkt sich zwar ein wenig auf den „lesbaren“ Teil aus, aber alles in allem ist es ein guter Kompromiss).
Ein ganz wesentlicher Vorteil der Sphinx-Toolchain ist der Umstand, dass Sphinx aus einem Quelltext unterschiedliche Ausgabeformate erzeugen kann, darunter PDF, Webseiten und ePub.
![digraph {
rankdir="LR";
"Projektordner"
[
shape=cylinder,
color=black,
style=filled,
fillcolor=grey,
fontcolor=black,
fontname="Source Code Pro",
label="RST-Quelltext",
width = 2;
height = 2;
];
"Sphinx-Compiler"
[
shape=cds,
color=mediumblue,
style=filled,
fillcolor=mediumblue,
fontcolor=white,
fontname="Source Sans Pro",
label="Sphinx-Compiler",
];
"html"
[
shape=note,
color=mediumblue,
fontcolor=mediumblue,
fontname="Source Sans Pro",
label="Webseite\nHMTL"
width = 2;
];
"LaTeX"
[
shape=note,
color=mediumblue,
fontcolor=mediumblue,
fontname="Source Code Pro",
label="LaTeX\ntex"
];
"LaTeX/Compiler"
[
shape=cds,
style=filled,
fillcolor="#a61017",
color="#a61017",
fontcolor=white,
fontname="Source Sans Pro",
label="LaTeX-Compiler"
];
"LaTeX/Compiler/pdf"
[
shape=note,
color="#a61017",
fontcolor="#a61017",
fontname="Source Sans Pro",
label="Print\nPDF"
width = 2;
];
"epub"
[
shape=note,
color=mediumblue,
fontcolor=mediumblue,
fontname="Source Sans Pro",
label="E-Book\nePUB"
width = 2;
];
"Projektordner" -> "Sphinx-Compiler";
"Sphinx-Compiler" -> "html" [color=mediumblue];
"Sphinx-Compiler" -> "epub" [color=mediumblue];
"Sphinx-Compiler" -> "LaTeX" [color=mediumblue];
"LaTeX" -> "LaTeX/Compiler" -> "LaTeX/Compiler/pdf" [color="#a61017"];
{rank = same; "LaTeX/Compiler/pdf"; html; epub; }
}](../../_images/graphviz-0004cb12028f9bd1784155e36d889f943fd7adc9.png)
Abb. 50 Sphinx kann verschiedene Ausgabeformate erstellen#
![digraph {
"Datei.rst"
[
shape = note,
color=crimson,
style=filled,
fillcolor=white,
fontcolor=crimson,
fontname="Source Code Pro",
label="index.rst",
];
"Compiler"
[
shape = box3d,
color=grey,
style=filled,
fillcolor=black,
fontcolor=white,
fontname="Source Sans Pro",
label="Compiler\n(Sphinx)",
];
"Datei.pdf"
[
shape = note,
color=black,
style=filled,
fillcolor=white,
fontcolor=black,
fontname="Source Serif Pro",
label="index.pdf",
];
"Datei.html"
[
shape = note,
color=blue,
style=filled,
fillcolor=white,
fontcolor=blue,
fontname="Source Sans Pro",
label="index.html",
];
"Datei.epub"
[
shape = note,
color=darkgreen,
style=filled,
fillcolor=white,
fontcolor=darkgreen,
fontname="Source Sans Pro",
label="index.epub",
];
rankdir = TB;
subgraph {
"Datei.rst" -> "Compiler" -> "Datei.pdf";
"Compiler" -> "Datei.html";
"Compiler" -> "Datei.epub";
# {rank = same; "Datei.rst" ; "Compiler"}
}
}](../../_images/graphviz-5c508aca5c6649c5b9a2f594fbac6e35082d2b39.png)
Abb. 51 Aus einer Quelltextdatei erzeugt der Compiler unterschiedliche Ausgabedateien und -formate#
Zur Erstellung von Print-Ausgaben im PDF-Format verwendet Sphinx das bewährte und leistungsfähige LaTeX-Schriftsatzsystem. Dies ermöglicht die Erstellung einer qualitativ hochwertige Druckausgabe bei gleichzeitig hoher Anpassungsmöglichkeit.
![digraph {
rankdir="LR";
"LaTeX"
[
shape=note,
color=mediumblue,
fontcolor=mediumblue,
fontname="Source Code Pro",
label="LaTeX\ntex"
];
"LaTeX/Compiler"
[
shape=cds,
style=filled,
fillcolor="#a61017",
color="#a61017",
fontcolor=white,
fontname="Source Sans Pro",
label="LaTeX-Compiler"
];
"LaTeX/Compiler/pdf"
[
shape=note,
color="#a61017",
fontcolor="#a61017",
fontname="Source Sans Pro",
label="Print\nPDF"
];
"LaTeX" -> "LaTeX/Compiler" -> "LaTeX/Compiler/pdf" [color="#a61017"];
}](../../_images/graphviz-d9183bf5ad281e9e39185bdbb60e80aa9e4b5e09.png)
Abb. 52 LaTeX verwendet einen Compiler, um die Ausgabe-PDF-Dateien zu erstellen#
Da Sphinx mit reST ein Klartextformat für die Quelltextdateien verwendet ist damit auch die Verwendung gängiger Versionskontrollsysteme, wie z. B. Git, möglich.
Fußnoten
Dieses Werk ist lizenziert unter der Creative Commons Namensnennung - Weitergabe unter gleichen Bedingungen 3.0 Österreich Lizenz (CC BY-SA 3.0 AT). Einzelne Beiträge und Medien können abweichend lizensiert sein.