Guidedog / Dokumentation 0.2.0

Kommandozeilenreferenz¶

Mit guidedog lassen sich Dokumentationsprojekte über die Kommandozeile verwalten, bauen, ansehen, übersetzen und konvertieren.

Allgemeine Syntax¶

guidedog <command> [arguments] [options]
guidedog --version
guidedog --help

Exitcodes¶

Tabelle 6 Exitstatus¶
Exitcode	Bedingung
`0`	Erfolg: Alle Vorgänge sind abgeschlossen; es gibt keine unbehandelten Fehler.
`1`	Build- oder Konvertierungsfehler; auch Warnungen, die durch `-W` als Fehler gelten.
`2`	Fehler in der Kommandozeilensyntax oder unbekannte Option.
`3`	Eine Ressourcengrenze wurde erreicht oder Speicher war nicht verfügbar.
`4`	Ein Dateivorgang oder externer Compiler ist fehlgeschlagen.
`5`	Interner Fehler; die Diagnose erläutert die Meldung.
`70`	Absturz; die vorherige Veröffentlichung bleibt verfügbar.

Befehlsübersicht¶

Tabelle 7 CLI-Befehle¶
Befehl	Aufgabe
`quickstart [DIR]`	Legt ein Dokumentationsprojekt mit direkt bearbeitbaren Vorlagen und Einstellungen an.
`build [BUILDER] [DIR]`	Baut das Dokumentationsprojekt im gewünschten Ausgabeformat.
`serve [DIR]`	Startet einen lokalen HTTP-Vorschauserver, der bei Dateiänderungen neu baut.
`clean [DIR]`	Entfernt erzeugte Dateien und Caches.
`convert INPUT`	Konvertiert eine einzelne Datei oder die Standardeingabe direkt.
`migrate [conf.py]`	Überträgt Sphinx-Konfigurationen aus `conf.py` in deklaratives `conf.toml`.
`intl <update\|stat>`	Aktualisiert PO-Kataloge oder zeigt den Übersetzungsstand.
`formats`	Listet eingebaute Reader, Renderer und Angaben zur Formatkonformität auf.
`gds <COMMAND>`	Verwaltet die Entwurfsunterlagen von Guidedog Discussions und ihren Lebenszyklus.

guidedog quickstart¶

Legt einen Projektordner mit conf.toml, index.rst, Vorlagen in _templates/ und Stilen in _static/ an:

# Interactive prompt
guidedog quickstart docs

# Non-interactive creation with predefined options
guidedog quickstart docs -q -p "My Project" -a "Author Name" -v 1.0 -l en

Optionen:

-q: Überspringt interaktive Fragen und verwendet die Kommandozeilenwerte.
-p, --project NAME: Legt den angezeigten Projektnamen fest.
-a, --author NAME: Legt den Namen des Autors oder der Organisation fest.
-v VERSION: Legt die Kurzversion fest, etwa 1.0.
-r RELEASE: Legt die vollständige Releasekennung fest, etwa 1.0.0-rc1.
-l LANGUAGE: Legt die Projektsprache fest; Standard ist en.
--sep: Legt getrennte Ordner source/ und build/ an.
--suffix EXT: Legt die Dateiendung der Quelldokumente fest; Standard ist .rst.

guidedog build¶

Koordiniert das Lesen, das Auflösen von Inhaltsbäumen und Querverweisen sowie die Ausgabe:

# Standard project build
guidedog build html docs
guidedog build pdf docs

# Sphinx-build compatibility syntax
guidedog build -b html docs _build/html
guidedog build -M html docs _build

Unterstützte Builder:

html: Erzeugt eine HTML-Website mit Suche und Navigation.
dirhtml: Erzeugt Verzeichnis-URLs wie dir/index.html.
singlehtml: Fasst alle Dokumente auf einer HTML-Seite zusammen.
pdf: Setzt PDF-Bücher mit Typst; Aliase sind latex und latexpdf.
text: Erzeugt eine Textdatei je Dokument.
gettext: Extrahiert übersetzbare Texte in GNU-gettext-POT-Vorlagen.
dummy: Analysiert Dokumentbäume und löst Verweise auf, ohne Ausgabedateien zu schreiben.

Buildoptionen:

-a: Schreibt alle Ausgabedateien unabhängig vom Änderungszeitpunkt.
-E: Baut die Umgebung ohne zwischengespeicherten Zustand neu auf.
-W: Lässt den Build bei Warnungen fehlschlagen.
--keep-going: Verarbeitet mit -W auch die übrigen Dokumente und meldet alle Fehler vor dem Beenden.
-n: Warnt bei allen unaufgelösten Querverweisen.
-j N / -j auto: Legt die Parserthreads fest; auto entspricht der Zahl der CPU-Kerne.
-D name=value: Überschreibt eine Einstellung aus conf.toml für diesen Aufruf, etwa -D language=de.
-D table.key=value: Setzt einen Schlüssel einer Tabelleneinstellung wie html_context und behält die übrigen Schlüssel, wie sphinx-build.
-t TAG: Definiert ein Tag für only-Direktiven.
-c DIR: Gibt den Ordner mit conf.toml an.
-C: Baut, ohne eine conf.toml zu laden.
-v: Zeigt zusätzliche Hinweise und Zeitstatistiken an.
-q: Zeigt nur Warnungen und Fehler.
--color=always|never|auto: Steuert die ANSI-Farbausgabe im Terminal.
--diagnostics=json: Schreibt maschinenlesbare JSON-Diagnosen auf die Standardfehlerausgabe.
--budget=MIB: Begrenzt den vom Projekthost gehaltenen Speicher; Standard sind 1024 MiB.
--memory=ram|disk: Bestimmt das Verhalten beim Ausschöpfen des Speicherbudgets.
--untrusted: Lässt eingebettetes Rohmarkup aus und deaktiviert Netzwerkabrufe. Das ist eine Fähigkeitsrichtlinie, keine Prozesssandbox.

guidedog serve¶

Startet einen lokalen HTTP-Server mit Dateiüberwachung. Änderungen an Quellen, Vorlagen oder Assets lösen einen Neubau und das Neuladen des Browsers aus:

# Serve current project on default port (8000)
guidedog serve docs

# Serve on custom port and host
guidedog serve docs --port 9000 --host 0.0.0.0

Optionen:

-p, --port PORT: Lokaler Port; Standard ist 8000.
--host HOST: IP-Adresse zum Binden; Standard ist 127.0.0.1.

guidedog clean¶

Löscht den Buildordner und den gespeicherten Umgebungszustand:

guidedog clean docs

guidedog convert¶

Konvertiert Dateien oder die Standardeingabe ohne Projektordner oder Konfiguration:

# Convert reStructuredText to HTML
guidedog convert guide.rst --output guide.html

# Convert Markdown to PDF
guidedog convert guide.md --to pdf --output guide.pdf

# Stream conversion from standard input to standard output
cat document.md | guidedog convert - --from commonmark --to html --output -

Optionen:

-o, --output FILE: Ausgabepfad; - bedeutet Standardausgabe.
--to FORMAT: Zielformat: html, pdf oder text; wird auch aus dem Dateinamen abgeleitet.
--from FORMAT: Quellreader: rst, commonmark, myst oder typst; wird auch aus der Endung abgeleitet.
--force: Überschreibt vorhandene Ausgabedateien ohne Rückfrage.
--strict: Schlägt bei jeder Warnung fehl.
--raw=allow|omit: Regelt eingebetteten Rohcode; Standard ist omit.
--emit-typst FILE: Schreibt den erzeugten Typst-Zwischencode in eine separate Datei.

guidedog migrate¶

Überträgt Sphinx-Einstellungen aus conf.py in deklaratives conf.toml:

# Convert conf.py in-place
guidedog migrate docs/conf.py

# Output to a specific file
guidedog migrate docs/conf.py -o docs/conf.toml --force

Optionen:

-o FILE: Schreibt in den angegebenen Pfad; - verwendet die Standardausgabe.
--force: Überschreibt vorhandene conf.toml-Dateien.

guidedog intl¶

Verwaltet Übersetzungskataloge für mehrsprachige Dokumentation:

# Step 1: Extract POT templates
guidedog build gettext docs

# Step 2: Create or update language PO catalogs
guidedog intl update -l de -l fr docs

# Check translation completion percentages
guidedog intl stat -l de docs

Optionen für intl update:

-l, --language LANG: Zielsprachencode; kann mehrfach angegeben werden.
-p, --pot-dir DIR: Pfad zu den extrahierten POT-Vorlagen.

guidedog formats¶

Zeigt eingebaute Reader, Renderer, Syntaxlexer und die Ergebnisse der Konformitätstests:

guidedog formats

guidedog gds¶

Verwaltet Architekturvorschläge (RFCs) von Guidedog Discussions:

guidedog gds new "Feature Title" --author="Name"
guidedog gds list --state=prediscussion
guidedog gds show 0003
guidedog gds promote 0003 --dry-run
guidedog gds state 0003 --to=accepted --reason="Consensus reached"
guidedog gds index
guidedog gds check --render
guidedog gds recover --rollback