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 2022-06-03