Gestalterische Anpassungen¶
Für die Grundwissen-Webseite nutze ich das Sphinx-Standard-Theme mit einigen
Anpassungen. Diese habe ich als Super-User direkt am zentralen Installationspfad
/usr/local/lib/python2.7/dist-packages/Sphinx-1.2b1-py2.7.egg/sphinx/
vorgenommen, so dass sie global für alle Dokumentations-Projekte gleichermaßen
gelten.
Mit der Basis-Installation und den folgenden Anpassungen kann die
Grund-Wissen-Homepage aus dem Quelltext-Archiv und
dem Graphik-Archiv durch den Aufruf make
html
bzw. make latexpdf
nachgebaut werden.[1]
Suchfeld-Kommentar löschen
Da sich die Dokumentation nicht auf Software-Quellcode bezieht, mag ich
unter dem Suchfeld in der Seitenleiste (“sidebar”) keinen Hinweis abgedruckt
haben, dass man einen Modul-, Klassen- oder Funktionsnamen eingeben könne.
Entsprechend habe ich die entsprechende Zeile in der Datei
themes/basic/searchbox.html
auskommentiert:
VORHER:
<p class="searchtip" style="font-size: 90%">
{{ _('Enter search terms or a module, class or function name.') }}
</p>
NACHHER:
<!--<p class="searchtip" style="font-size: 90%">-->
<!--{{ _('Enter search terms or a module, class or function name.') }}-->
<!--</p>-->
Kontakt-Link auf jeder HTML-Seite hinzufügen
In der Fußnotenzeile sollte ein Link auf Kontakt/Impressum eingefügt werden. Das
geschieht in themes/basic/layout.html
:
VORHER:
{%- if last_updated %}
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.
{% endtrans %}
{%- endif %}
NACHHER:
{%- if last_updated %}
{% trans last_updated=last_updated|e %}
Zuletzt aktualisiert am {{ last_updated }}.
<a href='http://grund-wissen.de/impressum.html'>Kontakt/Impressum</a>
{% endtrans %}
{%- endif %}
Kopfzeile der Druckversion entfernen
Normalerweise erscheint in der erzeugten PDF-Datei in der Kopfzeile jeder
Seite ein Versionshinweis. Um dies zu deaktivieren, muss die Datei
texinputs/sphinx.sty
an zwei Stellen abgeändert werden. Zum einen muss
die \fancyhead
-Zeile, die den Versions-Eintrag erzeugt, mit einem
%
-Zeichen auskommentiert werden. Zum anderen kann der Strich zwischen
Kopfzeile und erster Textzeile entfernt werden, indem ihr Wert auf 0.0
gesetzt wird:
VORHER:
\fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}}
...
\renewcommand{\headrulewidth}{0.4pt}
NACHHER:
% \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}}
...
\renewcommand{\headrulewidth}{0.0pt}
Tabellen zentrieren
Normalerweise werden Tabellen im Latex-Output linksbündig dargestellt.
Persönlich sind mir zentrierte Tabellen lieber. Daher habe ich die
(umfangreiche) Datei writers/latex.py
, speziell die Funktion
depart_table(self, node)
, etwas abgeändert:
VORHER:
if not self.table.longtable and self.table.caption is not None:
self.body.append(u'\n\\begin{threeparttable}\n'
u'\\capstart\\caption{%s}\n' % self.table.caption)
elif self.table.has_verbatim:
self.body.append('\n\\begin{tabular}')
endmacro = '\\end{tabular}\n'
elif self.table.has_problematic and not self.table.colspec:
# if the user has given us tabularcolumns, accept them and use
# tabulary nevertheless
self.body.append('\n\\begin{tabular}')
endmacro = '\\end{tabular}\n'
else:
self.body.append('\n\\begin{tabulary}{\\linewidth}')
endmacro = '\\end{tabulary}\n'
[...]
if not self.table.longtable and self.table.caption is not None:
self.body.append('\\end{threeparttable}\n')
NACHHER:
if not self.table.longtable and self.table.caption is not None:
self.body.append(u'\n\n\\begin{table}\\centering\n'
u'\\capstart\\caption{%s}\n' % self.table.caption)
if self.table.longtable:
self.body.append('\n\\begin{longtable}')
endmacro = '\\end{longtable}\n\n'
elif self.table.has_verbatim:
self.body.append('\n\\begin{center}\\begin{tabular}')
endmacro = '\\end{tabular}\\end{center}\n\n'
elif self.table.has_problematic and not self.table.colspec:
self.body.append('\n\\begin{center}\\begin{tabular}')
endmacro = '\\end{tabular}\\end{center}\n\n'
else:
self.body.append('\n\\begin{center}\\begin{tabulary}{\\linewidth}')
endmacro = '\\end{tabulary}\\end{center}\n\n'
[...]
if not self.table.longtable and self.table.caption is not None:
self.body.append('\\end{table}\n\n')
Auch in der HTML-Ausgabe möchte ich Tabellen gerne zentriert haben;
gleichzeitig sollen die Fußnoten, die von Sphinx ebenfalls in Tabellen-Form
dargestellt werden, linksbündig bleiben. Um dies zu erreichen, habe ich in
der Datei themes/basis/static/basic.css_t
den Eintrag table.docutils
folgendermaßen ergänzt:
table.docutils {
border: 1px solid gray;
border-collapse: collapse;
margin-left: auto;
margin-right: auto;
}
table.docutils.footnote, table.docutils.citation {
border: 0px;
border-collapse: collapse;
margin-left: 0;
}
table.docutils.footnote td, table.docutils.citation td {
border: 0px;
}
Zeilenumbruch bei langen Navigationszeilen ermöglichen
In der obersten Zeile einer jeden mit Sphinx erstellten HTML-Seite wird eine
Navigations-Leiste angezeigt. Bei einer umfangreichen Dokumentation mit vielen
Unterabschnitten kann es vorkommen, dass auf kleinen Bildschirmen hierbei ein
Zeilenumbruch nötig ist – der letzte Listeneintrag wird also in eine neue
Zeile geschrieben. In der Grundversion wird hierbei die Seitenüberschrift
verschoben. Um dies zu vermeiden, muss folgender Eintrag in der Datei
themes/basis/static/basic.css_t
ergänzt werden:
VORHER:
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
NACHHER:
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
min-height: 2em;
height: auto;
overflow: hidden;
}
Durch den Eintrag height: auto
wird die Höhe der Navigations-Leiste
automatisch angepasst. Der Eintrag overflow: hidden;
fügt anschließend bei
Bedarf automatisch eine (wieder ganz von links beginnende) neue Zeile ein.
Mehrspaltige Aufzählungen (hlist) in LaTeX
Mit der hlist
-Umgebung kann man mit Sphinx mehrspaltige Tabellen erstellen.
Der Code dafür sieht etwa so aus:
.. hlist::
:columns: 2
* Item 1
* Item 2
* ...
Während die HTML-Ausgabe ausgezeichnet funktioniert, werden hlist
-Umgebungen
vom LaTeX-Übersetzer wie “normale” Listen behandelt. Persönlich verwende ich
in den allermeisten Fällen zweispaltige hlists
, so dass ich mir in der Datei
writers/latex.py
mit folgendem Trick Abhilfe für den erstellten LaTeX-Code
geschaffen habe:
VORHER:
\usepackage{sphinx}
[...]
def visit_hlist(self, node):
self.compact_list += 1
self.body.append('\\begin{itemize}\\setlength{\\itemsep}{0pt}'
'\\setlength{\\parskip}{0pt}\n')
[...]
def depart_hlist(self, node):
self.compact_list -= 1
self.body.append('\\end{itemize}\n')
NACHHER:
\usepackage{sphinx}
\usepackage{multicol}
def visit_hlist(self, node):
self.compact_list += 1
self.body.append('\\begin{multicols}{2}')
self.body.append('\\begin{itemize}\\setlength{\\itemsep}{0pt}'
'\\setlength{\\parskip}{0pt}\n')
[...]
def depart_hlist(self, node):
self.compact_list -= 1
self.body.append('\\end{itemize}\n')
self.body.append('\\end{multicols}')
Damit werden alle hlists
in der Druckversion als zweispaltige Aufzählungen
dargestellt.[2]
Darstellung von Subparagraphen und Rubriken anpassen
Bei umfangreichen Dokumentationen mit vielen ineinander geschachtelten
Abschnitten können auch Sub-Paragraphen als Überschriften vorkommen.[3] Damit
diese – wie andere Überschriften auch – in Latex ebenfalls in blauer
Schriftfarbe gedruckt werden, ist die Datei texinputs/sphinx.sty
hinter um
folgenden Eintrag zu ergänzen:
VORHER:
\titleformat{\section}{\Large\py@HeaderFamily}%
{\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsection}{\large\py@HeaderFamily}%
{\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsubsection}{\py@HeaderFamily}%
{\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\paragraph}{\small\py@HeaderFamily}%
{\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
NACHHER:
\titleformat{\section}{\Large\py@HeaderFamily}%
{\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsection}{\large\py@HeaderFamily}%
{\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsubsection}{\py@HeaderFamily}%
{\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\paragraph}{\small\py@HeaderFamily}%
{\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subparagraph}{\small\py@HeaderFamily}%
{\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
Darstellung von Verbatim-Boxen anpassen
Um Code-Beispiele in LaTeX besser hervorzuheben, habe ich in der Datei
texinputs/sphinx.sty
die Farben für die Verbatim-Umgebung und ihre
Umrandung etwas angepasst:
VORHER:
\definecolor{VerbatimColor}{rgb}{1,1,1}
\definecolor{VerbatimBorderColor}{rgb}{1,1,1}
NACHHER:
\definecolor{VerbatimColor}{rgb}{0.97,0.97,1}
\definecolor{VerbatimBorderColor}{rgb}{0.75,0.75,1}
Die Boxen werden so in einem schwachen Blau mit einem ebenfalls leicht blauen Rahmen gedruckt.
Titelseite gestalten
Nach persönlichem Geschmack habe ich die Titelseite etwas abgewandelt –
insbesondere wollte ich dort einen Link auf die URL der Homepage einfügen.
Hierbei habe ich die Datei texinputs/sphinxmanual.cls
etwas angepasst:
VORHER:
\begin{flushright}
\sphinxlogo
{\rm\Huge\py@HeaderFamily \@title \par}
{\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}
\vfill
{\LARGE\py@HeaderFamily
\begin{tabular}[t]{c}
\@author
\end{tabular}
\par
}
\vfill\vfill
{\large
\@date \par
\vfill
\py@authoraddress
\par
}
\end{flushright}
\par
NACHHER:
\begin{flushright}
\sphinxlogo
{\rm\Huge\py@HeaderFamily \@title \par}
\vfill
{\em\large\py@HeaderFamily \py@release\releaseinfo \par}
{\em\py@HeaderFamily Aktualisiert am \@date \par}
\vfill
{\rm\Large\py@HeaderFamily
\begin{tabular}[t]{c}
\@author
\end{tabular}
\par
}
\vfill\vfill
{\Large
\url{http://www.grund-wissen.de}
}
\end{flushright}
\par
Zusätzlich habe ich in der Datei writers/latex.py
beide Vorkommnisse der
Bezeichnung “Release” durch “Version” ersetzt.
Anmerkungen:
[1] | Der Graphik-Pfad muss gegebenenfalls noch so angepasst werden, dass das
Hauptverzeichnis der Bilder als pics -Ordner im Hauptpfad der
Dokumentation abgelegt ist. |
[2] | Hierbei muss das LaTeX-Paket multicol installiert sein. Sollte dies
nicht der Fall sein, kann es von der CTAN-Projektseite herunter
geladen werden und gemäß dem üblichen Installations-Schema nachinstalliert werden. |
[3] | Das gilt insbesondere auch für mit .. rubric:: Titel erzeugte
Rubriken. Diese werden ohne die obigen Anpassungen in schwarzer Farbe
und größer als die Paragraphen-Überschriften dargestellt. |