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
extensions = [
"sphinx_rtd_theme",
]
Extensions
- Tabs
Diese Extension ist nicht mit
man
- oderpdf
-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
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
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
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):
.. 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-09-30