Guidedog¶
Einmal schreiben. Gut erklären. Im Web und auf Papier veröffentlichen.
Guidedog erzeugt eine Dokumentationswebsite und ein PDF-Buch aus denselben reStructuredText- oder Markdown-Dateien. Sie schreiben den Text einmal; Guidedog hält beide Ausgaben auf demselben Stand.
Eine einfache Textdatei geht hinein. Guidedog macht daraus eine Webseite und eine Buchseite.
Was es tut¶
- Eine Website. Seiten mit Navigation, Suche, hervorgehobenem Code sowie hellem und dunklem Design, aus Jinja-Vorlagen, die Sie beliebig ändern können.
- Ein PDF-Buch. Kapitel, Querverweise, Abbildungen, Tabellen, Fußnoten und ein Register, von Typst gesetzt, mit Silbentrennung für jede Sprache.
- reStructuredText und Markdown. Direktiven, Rollen, Toctrees und Querverweise funktionieren so, wie Sphinx-Nutzer es erwarten, und MyST-Markdown kann daneben stehen.
- Übersetzungen. Gettext-Kataloge bringen ein Projekt in andere Sprachen. Chinesischer, japanischer, koreanischer und Hindi-Text wird auf dem Bildschirm und auf Papier richtig gesetzt.
- Diagramme, Mathematik und API-Seiten. Graphviz-Diagramme, LaTeX-Formeln und eine Odin-API-Referenz, die aus dem Quellcode gelesen wird.
- Klare Fehlermeldungen. Eine Meldung sagt, was falsch ist, wo, und wie man es behebt. Ein fehlgeschlagener Build lässt die letzte gute Website unverändert.
Ein Programm¶
Guidedog ist eine einzige ausführbare Datei. Sie brauchen keine Python-Umgebung, keine LaTeX-Installation und keine separaten Theme- oder Erweiterungspakete. Die Konfiguration ist eine TOML-Datei, und Vorlagen sind gewöhnliche Dateien in Ihrem Projekt, die Sie bearbeiten können.
Manches kommt weiterhin von außen. Guidedog kann mit eingebautem Typst und Graphviz übersetzt werden; ohne sie verwendet es die auf Ihrem System installierten Programme typst und Graphviz. Unter Linux und macOS nutzt es außerdem einige Systembibliotheken, etwa libcurl.
Einmal schreiben, beides sehen¶
Links steht reStructuredText. Rechts steht, was Guidedog auf dieser Seite daraus gemacht hat. Der PDF-Builder setzt dieselben Zeilen als Buchseite.
.. note::
Guidedog liest Ihren Text nur einmal.
*Dieselben* Dateien werden zu einer **Website**
und zu einem **Buch**:
.. list-table::
:header-rows: 1
* - Builder
- Ergebnis
* - ``html``
- Eine Website
* - ``pdf``
- Ein PDF-Buch
Dieselben Dateien werden zu einer Website und zu einem Buch:
| Builder | Ergebnis |
|---|---|
html |
Eine Website |
pdf |
Ein PDF-Buch |
Das Handbuch als PDF-Buch ist ein Beispiel für das Ergebnis auf Papier. Es entsteht aus denselben Dateien wie die Website des Handbuchs.
Loslegen¶
Laden Sie das Archiv für Ihr System aus der neuesten Version herunter, legen Sie guidedog in Ihren PATH und erstellen Sie ein Projekt:
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
quickstart schreibt conf.toml, index.rst und Vorlagen, die Sie bearbeiten können. serve baut die Website neu, während Sie schreiben. Das Tutorial führt durch ein erstes Projekt. Um Guidedog aus dem Quellcode zu bauen, installieren Sie Odin und folgen Sie der Anleitung im Repository.
Design-Diskussionen¶
Die Designentscheidungen von Guidedog sind als nummerierte Diskussionen aufgeschrieben: das Problem, die Alternativen, die Entscheidung und die Belege. Sie können jede im Web lesen oder als PDF herunterladen.