.. highlight:: ReST
.. _Thema-SphinxToolchain:
Sphinx-Toolchain
#################
.. sectionauthor:: 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.
.. graphviz::
:caption: Sphinx kann verschiedene Ausgabeformate erstellen
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; }
}
.. graphviz::
:caption: Aus einer Quelltextdatei erzeugt der Compiler unterschiedliche Ausgabedateien und -formate
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"}
}
}
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.
.. graphviz::
:caption: LaTeX verwendet einen Compiler, um die Ausgabe-PDF-Dateien zu erstellen
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"];
}
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.
-----
.. rubric:: Fußnoten
.. [1] `https://lwn.net/Articles/705224/ `_
.. [2] `https://en.wikipedia.org/wiki/ReStructuredText `_
..
eigentliche Projektordner wird als
„``/``“ (*„root“*, engl. *Wurzel*) bezeichnet. Hier finden sich
alle projektrelevanten Dateien (Quell-Textdateien,
Konfigurationsdateien, ...) und Unterornder, insbesonders:
- der Quellcode (Verzeichnis)
- Konfigurationsdatei (``conf.py``), die Parameter für Ihre
Projekt
- ein ``Makefile`` (oder ~ make.bat ~), das Parameter für den Erstellungsprozess definiert
- Automatisch erze