Sphinx

Links:

Ein Dokumentationsprojekt erstellen:

sphinx-quickstart

Anschliessend rst-Dateien im Verzeichnis source ablegen.

Output-Formate („Builder“) sind:

sphinx-build -b epub source build
sphinx-build -b html source build
sphinx-build -b man source build
sphinx-build -b singlehtml source build
sphinx-build -b text source build

Build Pipelines sind:

sphinx-build -M info source build
sphinx-build -M latexpdf source build (erzeugt Latex-Dateien und das PDF-Dokument)

Anfangs laufen die Collectors - diese lesen alle Dokumente ein und bereiten unter anderem den Dokumentenbaum („toctree“) vor. Im Anschluss daran werden die Adapters ausgeführt, die zum Beispiel auch für die Generierung des Index sorgen.

Installation und Konfiguration

mkdir -p /opt/venv/
cd /opt/venv
python3 -m venv sphinx3
source sphinx3/bin/activate

pip install sphinx sphinx-sitemap myst_parser

Themes

Sphinx „Read the Docs“ Theme (rtd) installieren:

pip install sphinx-rtd-theme

conf.py

extensions = [
    "sphinx_rtd_theme",
]

Extensions

Tabs

Diese Extension ist nicht mit man- oder pdf-Output kompatibel.

Installation:

pip install sphinx-tabs

$EDITOR config.py

extensions = [
    "sphinx_tabs",
]

Verwendung:

.. tabs::

    .. tab:: Tab1

        Text mit Code

            $ pip install sphinx
            $ sphinx-build --version

    .. tab:: Tab2

        Text für Tab2

Output-Formate

PDF

Es gibt drei Möglichkeiten, ein PDF-Dokument aus den rst-Dateien zu erzeugen (wer nur Teile aus dem rst benötigt, kopiert das rst-Projekt in einen anderen Ordner und löscht dort die nicht benötigten Teile raus, inkl. Anpassung der enthaltenen index.rst-Dateien).

LatexPDF

Bevorzugt, da wesentlich schönerer Output als rst2pdf:

dnf install latexmk texlive-collection-latexrecommended texlive-collection-fontsrecommended texlive-collection-latexextra

conf.py

latex_documents = [
    ('index', 'yourdoc.tex', u'DocName', u'YourName', 'manual'),
]

sphinx-build -b latex doc/source/ doc/latex/

Die Latex-Dokumente finden sich anschliessend in doc/latex.

Anschliessend sollte die Datei yourdoc.tex bearbeitet werden:

\title{DocName}
\date{2022-01-12}
\author{Linuxfabrik GmbH}

% Landscape orientation
\usepackage[screen,margin=0.8in]{geometry}

% Presentation Type
\usepackage{geometry}
\geometry{landscape}

Um daraus das PDF zu generieren:

cd latex
pdflatex yourdoc.tex

PDF findet sich dann in yourdoc.pdf.

rst2pdf

Doku auf http://ralsina.me/static/manual.pdf. Hässlich.

pip install rst2pdf

conf.py

extensions = [
    "rst2pdf.pdfbuilder",
]

rst2pdf source/index.rst -o build/pdf/index.pdf --language=de --stylesheets=source/rst2pdf.stylesheet --footer="2018-08-14 - Linuxfabrik GmbH, Zürich"
rst2pdf --print-stylesheet

Firefox

Sphinx-Doku im HTML-Format im Firefox anschauen und dessen „Print > Save to PDF“-Funktion nutzen.

Blog

Wer auf Basis von rst-Dateien einen Blog aufbauen möchte, kann ABlog verwenden. Das Layout ist ähnlich zu HTMLy. Siehe https://ablog.readthedocs.io/manual/ablog-quick-start/

pip install ablog

ablog start
ablog build -s source -w build

Unterschied zu sphinx-build -b html source build: ablog baut Unterverzeichnisse in der URL-Struktur, also beispielsweise blog/2018/index.html.

Blog-Post erstellen

Damit ein Blog-Artikel richtig verlinkt werden kann, sollte der Dateiname der h1-Überschrift entsprechen, und es muss folgender Metadaten-Header verwendet werden (wobei „redirect“ nur verwendet wird, wenn man Google umleiten möchte):

2020/12/das-ist-meine-ueberschrift.rst

.. post:: 2020-12-31
   :tags: alphabetische, tag-liste
   :author: lf
   :redirect: 2017/06/old-page-name-for-the-post
   :nocomments:

Das ist meine Überschrift
=========================

Ganz viel Lorem ipsum.

Blog builden - lokal

Nach Erstellung des Contents wird der Blog gebaut:

cd ~/Nextcloud/rst/projects
ablog build -s blog -w /tmp/build/blog

Blog-Webseite simulieren

Wer lokal testen möchte, wie sich der Blog auf einem Webserver „anfühlt“, startet einfach den in Python integrierten Webserver:

cd /tmp/build/blog
python -m http.server 8080

Zugriff auf den Blog dann über http://localhost:8080

Blog builden und Online aktualisieren

ablog build -s blog -w /root/build/blog

Blog anpassen

Das Customizing geschieht wie bei Sphinx üblich über die _static/custom.css und/oder _static/custom.js. In letztere wird beispielsweise auch der Javascript-Code für Matomo/Piwik/Google Analytics untergebracht.

Integration von Matomo/Piwik

In der _static/custom.js einfügen:

// Matomo
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
_paq.push(["setDocumentTitle", document.domain + "/" + document.title]);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="https://analytics.example.com/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '99']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.type='text/javascript'; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();

Troubleshooting

myfile.rst:49: WARNING: Inline literal start-string without end-string.: Möglicherweise enthält eine Inline Code-Zeichenkette (jeweils eingeschlossen von doppelten Backticks) vor den abschliessenden Backticks ein oder mehrere Leerzeichen.

Built on 2024-04-18