Formeln und Fußnoten mit Sphinx, ein Workaround mit dem Sphinx-RtD-Theme

Ich bin habe mich wieder ein wenig mit Sphinx und reStructuredText versöhnt. Denn für die heute morgen angesprochenen Probleme mit Formeln und Fußnoten habe ich einen einigermaßen zufriedenstellenden Workaround gefunden. Dieser Workaround heißt Read the Docs Sphinx Theme.

Zwar kann dieses Template nicht die meiner Meinung nach fehlerhaften Design-Entscheidungen der Sphinx- oder DocUtils-Entwickler beiseite schaffen, aber die CSS-Gurus des Templates haben es geschafft, die Folgen doch weitestgehend abzumildern. Die Formeln-Numerieirung wird in diesem Template über den Formeln angezeigt (immer noch nicht schön, aber damit kann ich leben), die Fußnoten werden kleiner und hochgestellt angezeigt und für die Fußnoteneinträge haben die Macher einen ganz charmanten und optisch überzeugenden Workaround gefunden (siehe Screenshot).

Leider ist das sphinx-rtd-theme nicht im Standard-Downlaod enthalten, aber es ist auf PyPi zu finden und daher erledigt ein

pip install sphinx-rtd-theme

die gesamte Installation. Danach ist noch die conf.py-Datei aufzubohren:

extensions = [
    ...
    "sphinx_rtd_theme",
]

html_theme = "sphinx_rtd_theme"

Wenn noch andere Extensions benutzt werden – in meinem Falle noch sphinx.ext.mathjax – sieht dieser Eintrag natürlich wie folgt aus:

extensions = [
  "sphinx.ext.mathjax",
  "sphinx_rtd_theme"
]

Danach läuft alles wie geschmiert. Jetzt muß ich nur noch herausbekommen, wie die in backticks eingeschlossenen Begriffe als <code> und nicht als <em> herausgerendert werden, dann bin ich schon fast wieder restlos glücklich. Still digging!

(Kommentieren)