Guidedog / Dokumentation 0.2.0

Konfigurationsreferenz¶

Jedes Projekt verwendet conf.toml im Stammordner. Guidedog liest deklarative TOML-Daten und führt keinen beliebigen Konfigurationscode aus.

Viele Schlüssel entsprechen Sphinx-Variablen aus conf.py. Das erleichtert die Migration mit guidedog migrate conf.py.

Minimale Konfiguration¶

Grundlegende Metadaten genügen. Für ausgelassene Schlüssel gelten Standardwerte:

project = "Field Notes"
author = "Your Name"
version = "1.0"
release = "1.0.0"
language = "en"
root_doc = "index"
source_suffix = [".rst", ".md"]
templates_path = ["_templates"]
html_static_path = ["_static"]
pdf_paper_size = "a4"

Projektmetadaten¶

Tabelle 8 Metadatenoptionen¶
Schlüssel	Typ	Standard	Beschreibung
`project`	Zeichenkette	`"Python"`	Angezeigter Name des Projekts.
`author`	Zeichenkette	`""`	Name des Autors oder der Organisation.
`copyright`	Zeichenkette	`""`	Urheberrechtsangabe im Seitenfuß.
`version`	Zeichenkette	`""`	Kurzversion, etwa `"1.0"`.
`release`	Zeichenkette	`""`	Vollständige Version einschließlich Alpha- oder Beta-Kennung, etwa `"1.0.0b1"`.
`language`	Zeichenkette	`"en"`	ISO-Sprachcode für Satz, Silbentrennung und Übersetzung, etwa `"de"` oder `"zh_CN"`.
`today`	Zeichenkette	`""`	Eigener Datumstext; sonst wird das aktuelle Datum mit `today_fmt` formatiert.
`today_fmt`	Zeichenkette	`""`	Formatstring für Dokumentdaten.

Allgemeine Optionen¶

Tabelle 9 Optionen zur Erkennung und Analyse¶
Schlüssel	Typ	Standard	Beschreibung
`root_doc`	Zeichenkette	`"index"`	Dokument für das Wurzelinhaltsverzeichnis.
`source_suffix`	Array	`[".rst"]`	Als Dokumentquellen erkannte Dateiendungen.
`exclude_patterns`	Array	`[]`	Glob-Muster für Dateien und Ordner, die bei der Quellsuche ausgelassen werden.
`include_roots`	Array	`[]`	Erlaubte externe Stammordner für Quelldateien.
`templates_path`	Array	`[]`	Ordner mit HTML- und PDF-Vorlagen; werden vor eingebauten Vorlagen durchsucht.
`extensions`	Array	`[]`	Zu aktivierende, nativ implementierte Sphinx-Erweiterungen, etwa `"sphinx.ext.autodoc"`.
`primary_domain`	Zeichenkette	`"py"`	Standarddomäne für Direktiven und Rollen ohne Präfix, etwa `"py"`, `"c"` oder `"odin"`.
`highlight_language`	Zeichenkette	`"default"`	Standardsprache für Codeblöcke ohne Sprachangabe.
`pygments_style`	Zeichenkette	`""`	Pygments-Hervorhebungsstil für das helle Thema.
`pygments_dark_style`	Zeichenkette	`""`	Syntaxhervorhebung für das dunkle Thema.
`smartquotes`	Boolescher Wert	`true`	Wandelt gerade Anführungszeichen und Striche in typografische Zeichen um.
`rst_prolog`	Zeichenkette	`""`	reStructuredText-Fragment vor jedem Dokument.
`rst_epilog`	Zeichenkette	`""`	reStructuredText-Fragment nach jedem Dokument.

Nummerierung und Mathematik¶

Tabelle 10 Nummerierungsoptionen¶
Schlüssel	Typ	Standard	Beschreibung
`numfig`	Boolescher Wert	`false`	Nummeriert Abbildungen, Tabellen und Codeblöcke automatisch.
`numfig_secnum_depth`	Ganzzahl	`1`	Gliederungstiefe in Abbildungsnummern; `1` ergibt etwa `Fig. 2.1`.
`numfig_format`	Tabelle	siehe unten	Nummernpräfixe für `"figure"`, `"table"` und `"code-block"`.
`math_number_all`	Boolescher Wert	`false`	Nummeriert alle abgesetzten Gleichungen automatisch.
`math_eqref_format`	Zeichenkette	`"({number})"`	Format für Gleichungsverweise mit `:eq:`.
`mathjax_path`	Zeichenkette	URL	CDN-Adresse oder lokaler Pfad des MathJax-JavaScript-Pakets.

Standardwerte für numfig_format:

[numfig_format]
figure = "Fig. %s"
table = "Table %s"
code-block = "Listing %s"
section = "Section %s"

Diagnosen und strenge Prüfung¶

Tabelle 11 Diagnoseoptionen¶
Schlüssel	Typ	Standard	Beschreibung
`nitpicky`	Boolescher Wert	`false`	Warnt bei unaufgelösten Querverweisen und ungültigen Zielen.
`nitpick_ignore`	Array	`[]`	Array aus `[type, target]`-Paaren, die von strengen Warnungen ausgenommen sind.
`suppress_warnings`	Array	`[]`	Codes der zu unterdrückenden Warnungskategorien.
`keep_warnings`	Boolescher Wert	`false`	Nimmt Warnungen in die veröffentlichten Dokumente auf.

HTML-Ausgabeoptionen¶

Tabelle 12 HTML-Optionen¶
Schlüssel	Typ	Standard	Beschreibung
`html_theme`	Zeichenkette	`"guidedog"`	Thema für die HTML-Ausgabe.
`html_theme_options`	Tabelle	`{}`	Schlüssel-Wert-Optionen für das HTML-Thema.
`html_title`	Zeichenkette	abgeleitet	Titel im Browserreiter.
`html_short_title`	Zeichenkette	abgeleitet	Kurztitel für die Navigationspfade.
`html_logo`	Zeichenkette	`""`	Logopfad relativ zum Quellordner.
`html_favicon`	Zeichenkette	`""`	Pfad zur Favicon-Datei.
`html_static_path`	Array	`[]`	Ordner, die in das ausgegebene `_static/` kopiert werden.
`html_extra_path`	Array	`[]`	Ordner, die unverändert in die Ausgabewurzel kopiert werden.
`html_css_files`	Array	`[]`	Zusätzliche CSS-Dateien, die HTML-Seiten laden.
`html_js_files`	Array	`[]`	Zusätzliche JavaScript-Dateien, die HTML-Seiten laden.
`html_permalinks`	Boolescher Wert	`true`	Fügt Absätzen und Abschnitten dauerhafte Links hinzu.
`html_permalinks_icon`	Zeichenkette	`"¶"`	Zeichen oder Text für dauerhafte Links.
`html_baseurl`	Zeichenkette	`""`	Kanonische Basis-URL für Sitemaps und Metadaten.
`html_context`	Tabelle	`{}`	Wörterbuch zusätzlicher Variablen für Jinja-Vorlagen.
`html_additional_pages`	Tabelle	`{}`	Zusätzliche Seiten: `{ "page_name" = "template.html" }`.

PDF- und Typst-Optionen¶

Tabelle 13 PDF-Optionen¶
Schlüssel	Typ	Standard	Beschreibung
`pdf_paper_size`	Zeichenkette	`"a4"`	Papierformat: `"a4"` oder `"us-letter"`.
`pdf_logo`	Zeichenkette	`""`	Logopfad für die Titelseite.
`pdf_toplevel_sectioning`	Zeichenkette	`"chapter"`	Oberste Buchgliederung: `"chapter"` oder `"part"`.
`pdf_show_urls`	Zeichenkette	`"no"`	URL-Anzeige im Druck: `"no"`, `"inline"` oder `"footnote"`.
`pdf_preamble`	Zeichenkette	`""`	Typst-Rohcode für den erzeugten Dokumentvorspann.
`pdf_font_paths`	Array	`[]`	Zusätzliche Suchordner für OTF-/TTF-Schriften.
`pdf_packages`	Zeichenkette	`"download"`	Strategie zur Paketauflösung: `"download"` oder `"offline"`.
`typst`	Zeichenkette	`"typst"`	Programmname oder absoluter Pfad zur Typst-CLI.

PDF-Bücher definieren¶

Die Tabelle [[pdf_documents]] definiert ein oder mehrere Bücher des Projekts:

[[pdf_documents]]
root = "index"
file = "guide.pdf"
title = "Field Notes Complete Guide"
author = "Author Name"

[[pdf_documents]]
root = "reference/index"
file = "reference.pdf"
title = "Field Notes Reference"
author = "Author Name"

MyST-Markdown-Optionen¶

Tabelle 14 MyST-Markdown-Optionen¶
Schlüssel	Typ	Standard	Beschreibung
`myst_enable_extensions`	Array	`["dollarmath"]`	Syntaxerweiterungen: `"colon_fence"`, `"deflist"`, `"dollarmath"`, `"fieldlist"`, `"tasklist"`, `"substitution"`.
`myst_heading_anchors`	Ganzzahl	`0`	Gliederungstiefe für automatische Titelanker; `0` deaktiviert sie.
`myst_substitutions`	Tabelle	`{}`	Variablenersetzungen in Markdown: `{key = "value"}`.
`myst_url_schemes`	Array	`["http", ...]`	Als externe Links erkannte URI-Schemata.
`myst_commonmark_only`	Boolescher Wert	`false`	Beschränkt den Parser auf CommonMark ohne MyST-Erweiterungen.

Intersphinx-Optionen¶

extensions = ["sphinx.ext.intersphinx"]
intersphinx_cache_limit = 5
intersphinx_timeout = 30

[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]

Den vollständigen Ablauf beschreibt Auf andere Projekte verweisen.

Python-autodoc-Optionen¶

Tabelle 15 Autodoc-Optionen¶
Schlüssel	Typ	Standard	Beschreibung
`autodoc_source_paths`	Array	`[]`	Modulsuchpfade für die statische Python-Analyse.
`autoclass_content`	Zeichenkette	`"class"`	Quelle des Klassen-docstrings: `"class"`, `"init"` oder `"both"`.
`autodoc_member_order`	Zeichenkette	`"alphabetical"`	Mitgliederreihenfolge: `"alphabetical"`, `"bysource"` oder `"groupwise"`.
`autodoc_typehints`	Zeichenkette	`"signature"`	Position der Typhinweise: `"signature"`, `"description"` oder `"none"`.
`autodoc_default_options`	Tabelle	`{}`	Standardoptionen für alle `auto*`-Direktiven.

Die vollständigen Erkennungsregeln stehen in Python mit autodoc dokumentieren.

Odin-API-Dokumentationsoptionen¶

Tabelle 16 Odin-Domänenoptionen¶
Schlüssel	Typ	Standard	Beschreibung
`odin_autoapi_dirs`	Array	`[]`	Quellordner für die Suche nach Odin-Paketen.
`odin_autoapi_root`	Zeichenkette	`"api"`	Ausgabeunterordner für erzeugte Odin-API-Dokumentation.
`odin_autoapi_options`	Array	`["members", "undoc-members"]`	Filter für einzuschließende Mitglieder.
`odin_autoapi_member_order`	Zeichenkette	`"source"`	Mitgliederreihenfolge: `"source"` oder `"alphabetical"`.

Die vollständige Verwendung der Odin-Domäne beschreibt Odin dokumentieren.

Internationalisierungsoptionen¶

Tabelle 17 i18n-Optionen¶
Schlüssel	Typ	Standard	Beschreibung
`locale_dirs`	Array	`["locales"]`	Suchordner für gettext-Kataloge.
`gettext_compact`	Boolescher Wert	`true`	Fasst Dokumentmeldungen je Ordner in einem Katalog zusammen.
`gettext_uuid`	Boolescher Wert	`false`	Schreibt stabile UUIDs in POT-Meldungen.
`gettext_auto_build`	Boolescher Wert	`true`	Kompiliert `.po` beim Build in binäre `.mo`-Kataloge.
`figure_language_filename`	Zeichenkette	`"{root}.{language}{ext}"`	Dateinamenvorlage zur Auswahl lokalisierter Bilder.

Den Übersetzungsablauf beschreibt Internationalisierung.