Ich möchte das von Sphinx und ReadTheDocs verwendete Thema mit meinen eigenen benutzerdefinierten Stilen erweitern.
Was ist der beste Weg, dies zu tun, damit meine Änderungen bleiben?
Ihr RTD-Dokument hat die folgende Struktur:
_static/ _templates/ conf.py Sie erstellen auch lokal mit sphinx-build oder sphinx-autobuild unter Verwendung des Standarddesigns, aber Ihr implementierter Server verwendet möglicherweise stattdessen sphinx-rtd-theme .
In dieser Illustration werde ich zeigen, wie man benutzerdefiniertes Styling für "hattnotes" erstellt, ein Konzept, das in MediaWiki-Dokumenten weit verbreitet ist und das grob dem Konstrukt admonition in RST entspricht . Sie können das, was hier gezeigt wird, anwenden, um ein benutzerdefiniertes CSS zu erstellen und es in Ihr Dokumentations-Set aufzunehmen.
Die benutzerdefinierte CSS-Datei sollte irgendwo unter dem _static/ -Verzeichnis liegen, da dort der Build-Prozess und die Skripts sie finden. Ich würde ein Unterverzeichnis css/ empfehlen, da Sie möglicherweise andere Anpassungen wie JavaScript-Dateien hinzufügen können.
Erstellen Sie Ihre benutzerdefinierte CSS-Datei und legen Sie sie in diesem Verzeichnis ab. Schreiben Sie Ihre Stilspezifikationen als Überlagerung zu dem, was in dem Design, das Sie im Build verwenden, bereits vorhanden ist. Nehmen Sie auch nicht an, ob Ihr Stil einen vorhandenen Stil im Design überschreiben wird, da Sie nicht garantieren können, dass Ihre Stile im Verhältnis zu den Standardstilen hinzugefügt werden.
Hier ist mein benutzerdefiniertes CSS für Hutnotes. Ich habe dies bei _static/css/hatnotes.css gespeichert.
Für das Standarddesign ist es ausreichend, eine Vorlage zu erstellen, die den Standard layout.html überschreibt, um das benutzerdefinierte CSS dem Layout hinzuzufügen. Die Verwendung von Vorlagen ist gut dokumentiert unter sphinxdoc.org . Setzen Sie in Ihrer Override-Vorlage einfach die Variable css-files (ein Array) mit einer angehängten Liste Ihrer benutzerdefinierten CSS-Dateien.
Hier ist meine Vorlage, die das hennotes CSS hinzufügt. Ich habe das als _templates/layout.html gespeichert.
Das ist alles, was Sie für das Standardthema tun müssen. Für das Sphinx / RTD-Thema gibt es einen zusätzlichen Schritt, wo Sie ...
Beim Sphinx / RTD-Thema wird Ihre Vorlage ignoriert. Anstatt den Vorlagenmechanismus zu verwenden, müssen Sie Ihrer conf.py -Datei eine Funktion hinzufügen, die die CSS-Datei zum Thema der App hinzufügt. Irgendwo in der Nähe, wo die conf-Datei das html_theme -Attribut setzt, fügen Sie etwas wie folgt hinzu:
Beachten Sie, dass diesmal kein _static/ am Anfang des Pfades steht. Die Funktion add_stylesheet() nimmt diesen Teil des Pfades an.
Nachdem Sie nun Ihre benutzerdefinierten Stile für das Standarddesign und das Sphinx / RTD-Design eingerichtet haben, können Sie sie in Ihrem Dokument verwenden.
Nach dem üblichen Paradigma, Stock Huntnotes als "Templates" in MediaWiki zu definieren (sorry, nicht dasselbe wie Templates in Sphinx und RTD), habe ich ein includes/ Verzeichnis eingerichtet, in dem alle meine Hattnotes gespeichert werden.
Hier erfahren Sie, wie Sie eine Hutnote mit den benutzerdefinierten Informationen erstellen. Diese Datei ist includes/hatnotes/stub-article.rst .
Hier richten wir unsere "stub" -Hatnote ein, um den Standard-Hattnotenstil, den grauen Hintergrund und ein "Stub" -Symbol als Inline-Bild zu verwenden, wobei der hatnote-icon -Stil auf das Bild angewendet wird.
Jetzt können wir die Datei als enthaltene Ressource in einem Dokument verwenden.
%Vor% Unabhängig davon, ob Sie das lokale Standardthema oder das Sphinx / RTD-Thema verwenden, wird die Haschnote mit den von Ihnen hinzugefügten Stilen gerendert, indem die _templates/layout.html -Schablone und das conf.py -Skript so konfiguriert werden, dass beide die benutzerdefinierte CSS-Datei enthalten Sie werden in das Verzeichnis _static/ gestellt.
Ihr doc-Repository enthält jetzt folgende Elemente:
_static/ - (fügt Ihr benutzerdefiniertes CSS dem Standardlayout hinzu)
css/ - (mit neuer Funktion zum Hinzufügen von benutzerdefiniertem CSS zum App-Thema)
Tags und Links css python-sphinx read-the-docs restructuredtext