Daß sich das Dokumentationswerkzeug Sphinx nicht ausschließlich für den Einsatz innerhalb von Python oder C/C++ Projekten eignet, mag allgemein bekannt sein. Aufgrund seiner Leistungs- und Anpassungsfähigkeit ist es durchaus auch verwendbar für die Entwicklung und Nutzung von Dokumentationsthemen außerhalb des IT-Bereichs. Mit ein paar Anpassungen lassen sich intelligente und attraktive HTML-Seiten generieren, die sich anschließend über jeden Web-Server veröffentlichen lassen. Aber nicht nur die Darstellung im Netz ist so möglich. Im Zusammenspiel mit einer LaTeX-Maschine1) lassen sich – zum Beispiel für begleitende Handouts – zusätzlich hochwertige PDF-Dateien gleichen Inhalts erzeugen.
Die folgenden Beispiele entstanden auf einem iMac mit OS X Version 10.10.5, also Yosemite. Sphinx wurde in der Version 1.3.1 installiert.
Make HTML
Für ein neues Dokumentationsprojekt muß im Wesentlichen die Datei conf.py angepaßt und ggf. eine zum gewählten Sphinx-Thema passende, aber alternative CSS-Datei erstellt werden. Bei der Konfigurationsdatei conf.py handelt es sich übrigens um eine echte Python-Datei und folgt somit den normierten Regeln der Python Syntax. Allzu große Formulierungsfreiheiten hat man also nicht.
Welche Sphinx-Version ist gegenwärtig installiert?
$ python Python 2.7.10 (default, Jul 14 2015, 19:46:27) [GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.39)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import sphinx >>> print sphinx.__version__ 1.3.1 >>> quit()
Oder auch so:
$ sphinx-quickstart --version Sphinx v1.3.1
Um ein neues Projekt zu starten reichen im Quiet-Modus zunächst drei Daten: Autor, Projektname und Versionsnummer
$ sphinx-quickstart -q -a "Rüdiger Huß" -p "Projekt Lorem Ipsum" -v 1 -l de Creating file ./conf.py. Creating file ./index.rst. Creating file ./Makefile. Creating file ./make.bat. ...
In den weiteren Schritten wird die zentrale, gerade eben erzeugte Konfigurationsdatei conf.py angepaßt. Einen Überblick über die bereits gesetzten Parameter erhält man auf diesem Weg:
$ cat conf.py | grep "^[^#].*"
import sys
import os
import shlex
extensions = []
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'Projekt Lorem Ipsum'
copyright = u'2015, Rüdiger Huß'
author = u'Rüdiger Huß'
version = '1'
release = '1'
language = 'de'
exclude_patterns = ['_build']
pygments_style = 'sphinx'
todo_include_todos = False
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'ProjektLoremIpsumdoc'
latex_elements = {
}
latex_documents = [
(master_doc, 'ProjektLoremIpsum.tex', u'Projekt Lorem Ipsum Documentation',
u'Rüdiger Huß', 'manual'),
]
man_pages = [
(master_doc, 'projektloremipsum', u'Projekt Lorem Ipsum Documentation',
[author], 1)
]
texinfo_documents = [
(master_doc, 'ProjektLoremIpsum', u'Projekt Lorem Ipsum Documentation',
author, 'ProjektLoremIpsum', 'One line description of project.',
'Miscellaneous'),
]
Die anderen, zur Zeit noch auskommentierten Parameter ließen sich zum Beispiel so auflisten:
$ cat conf.py | grep "^#[a-z].*"
#sys.path.insert(0, os.path.abspath('.'))
#needs_sphinx = '1.0'
#source_encoding = 'utf-8-sig'
#today = ''
#today_fmt = '%B %d, %Y'
#default_role = None
#add_function_parentheses = True
#add_module_names = True
#show_authors = False
#modindex_common_prefix = []
...
Sollte man einmal den Überblick über die Projektdateien verloren haben, kann man nach Begriffen oder Textpassagen innerhalb der Dateien suchen:
$ find . -type f -print0 | xargs -0 grep -n "tocdepth"
Binary file ./_build/doctrees/environment.pickle matches
./_build/latex/ProjektLoremIpsum.tex:19:\setcounter{tocdepth}{2}
./_build/latex/sphinxmanual.cls:31:\setcounter{tocdepth}{1}
./conf.py:218:'preamble': '\setcounter{tocdepth}{2}',
Das Standard-Thema der Sphinx-Version 1.3 ist Alabaster, dennoch kann es innerhalb der Konfigurationsdatei explizit herangezogen werden:
import alabaster extensions = ['alabaster'] html_theme = 'alabaster'
Möchte man auf den Link zur Quellcode-Anzeige in der Sidebar verzichten, muß diese Anpassung in der Datei conf.py vorgenommen werden:
html_show_sourcelink = False
Ein Logo links oben in der SideBar: Das Logo wird als png-Datei im Unterverzeichnis _static abgelegt und sollte nicht größer als 200 Pixel im Quadrat sein.
html_static_path = ['_static'] html_logo = '_static/rh-logo-blau-200.png'
CSS-Anpassungen
Um das Thema Alabaster auf die eigenen Vorstellungen anpassen zu können wird eine weitere CSS-Datei benötigt, die die Voreinstellungen des Themas während der Übersetzung überschreibt. Dazu muß im Projekt-Verzeichnis _templates
templates_path = ['_templates']
eine Datei layout.html mit folgendem Inhalt erzeugt werden:
$ cat ./_templates/layout.html
{# layout.html #}
{# Import the theme's layout. #}
{% extends "!layout.html" %}
{% set css_files = css_files + ['_static/style.css'] %}
Damit ist dem System die Existenz der alternativen CSS-Datei style.css in dem lokalen Projekt-Verzeichnis _static bekannt gemacht worden. In dem Beispiel wurde der Textabstand der H1-Überschriften nach unten vergrößert und die Farbe der Headlines H2 bis H6 individualisiert:
$ cat ./_static/style.css
/*
Stilanpassungen
*/
/* -- body styles ------------------------------------------------------ */
div.body h1 {
margin-top: 0;
padding-top: 0;
padding-bottom: 20px;
font-size: 240%;
}
div.body h2 { font-size: 180%; color: #6D4100; }
div.body h3 { font-size: 150%; color: #6D4100; }
div.body h4 { font-size: 130%; color: #6D4100; }
div.body h5 { font-size: 100%; color: #6D4100; }
div.body h6 { font-size: 100%; color: #6D4100; }
Make LaTeX
Um nun aus der gleichen Quelle per LaTeX gestaltete PDF-Dokumente zu erhalten, kann die Konfigurations-Datei conf.py noch in den nachfolgenden Punkten Anpassungen erhalten.
latex_elements = {
'papersize': 'a4paper',
'pointsize': '11pt',
'preamble': '\setcounter{tocdepth}{2}',
'classoptions': ',openany,oneside',
'babel' : '\\usepackage[ngerman]{babel}'
}
latex_documents = [
(master_doc, 'ProjektLoremIpsum.tex', u'Lorem Ipsum Dokumentation',
u'Rüdiger Huß', 'manual'),
]
latex_logo = '_static/rh-logo-blau-500.png'
LaTeX wird ein Dokument vom Typ »report« in der Größe A4 und 11 Punkt Schriftgröße erstellen. Das Inhaltsverzeichnis soll auf jeden Fall bis zur dritten Ebene (subsection) aufgegliedert werden. Es wird auf Leerseiten verzichtet und der Report wird nicht gebunden, er ist also einseitig. Außerdem wird noch ein Logo auf der ersten Seite oben eingefügt, das aber etwas größer sein sollte als jenes in der HTML-Version (Sidebar oben). Dieses Logo wird ebenfalls als png-Datei in dem Verzeichnis _static abgespeichert. Die Übersetzung der Dokumentation erfolgt so:
$ make clean $ make html $ make latex $ cd ./_build/latex $ make
Alternativ kann man statt make latex auch make latexpdf eingeben. Damit erspart man sich den Verzeichniswechsel und das anschließende make zum erzeugen der PDF-Datei. Um die Ergebnisse des Prozesses besser analysieren zu können, kann der Output in eine Datei zur anschließenden Text-Analyse abgezweigt werden.
$ make | tee tellme.txt $ cat tellme.txt | grep -i 'warn' $ cat tellme.txt | grep -i ' not ' ...
Mittels Sphinx ist es vergleichsweise einfach sowohl ansprechende, komplexe Online-Dokumentationen als auch hochwertige Offline-Druckwerke zu erstellen. Wenngleich die Auszeichnungssprache von Sphinx relativ schnell erlernbar ist, so ist die diesbezügliche Lernkurve bei LaTeX (pdfLaTeX) doch erheblich steiler.
rh2015-12-001
1) LaTeX im Sinne des Artikels ist auch pdfLaTeX, XeLaTeX, usw.