Kompatibilität mit Sphinx¶
Guidedog folgt Sphinx, wo dies die Projektmigration erleichtert, und prüft die Kompatibilität für jede Funktion. Python-Konfiguration und beliebige Python-Erweiterungen werden nicht ausgeführt. Ein erfolgreicher Build belegt einen erfolgreichen Build, keine vollständige Gleichwertigkeit.
Projekte und Veröffentlichung¶
| Operation | Implementiertes Verhalten |
|---|---|
| Projektstruktur und Build-Optionen | Quell- und Ausgabeverzeichnisse im Sphinx-Stil; -a -E -W -n -D -t -j -b -M -c -C. |
| Konfiguration | TOML-Daten mit den vertrauten Sphinx-Namen. Die Migration wandelt Literale um und meldet berechnete Werte. |
| HTML-Builder | html, dirhtml und singlehtml. Anker in der Einzelseite enthalten den Dokumentnamen. |
| Weitere Builder | text, gettext und dummy. pdf verwendet Typst; latex und latexpdf wählen denselben Weg. |
| Vorlagen | Guidedogs Jinja-Implementierung, typisiertes html_context, Layout-Vererbung und zusätzliche Seiten. |
| Inkrementelle Builds | Änderungen an Quellen, Abhängigkeiten, Vorlagen, Konfiguration und Referenzsuchen machen die betroffene Ausgabe ungültig. |
| Veröffentlichung | Eine vollständige Generation. Bei einem fehlgeschlagenen Build bleibt die zuvor veröffentlichte Generation erhalten. |
-D akzeptiert für boolesche Werte true und false oder 1 und 0. Ein Projekt mit contents ohne index kann contents unter Ausgabe einer Warnung als Wurzel verwenden. Zusätzliche Vorlagenseiten liegen auch bei dirhtml als Dateien im Site-Stamm. Der genaue Vertrag steht in Vorlagen.
Unveränderte Seiten melden ihre Diagnosen erneut. Damit bedeutet -W bei einem sauberen und einem unveränderten Build dasselbe. Die Seite eines gelöschten Dokuments wird entfernt. Die Veröffentlichung nutzt ein wiederherstellbares Journal. Der nächste Build bereinigt einen unterbrochenen Commit. Invariante und Plattformgrenzen stehen in Eine vollständige Generation veröffentlichen.
Die Builder epub, man, texinfo, linkcheck, doctest, coverage und changes sind nicht verfügbar. Bei ihrer Angabe erscheint eine Korrekturhilfe. tools/linkcheck im Repository ist ein separates Prüfwerkzeug.
Quellformate¶
| Reader | Nachweise und Grenzen |
|---|---|
| reStructuredText | 98 Korpusquellen stimmen mit den verglichenen Docutils-Bäumen und Kennungen überein. Quellpositionen und einige Verwaltungsattribute sind vom Vergleich ausgenommen. |
| CommonMark 0.31.2 | Alle 652 Beispiele der Spezifikation bestehen. |
| MyST 0.16.1 reference | 215 von 218 Reader-Testfällen und 8 von 10 Sphinx-Testbuilds stimmen überein. Die übrigen Unterschiede sind dokumentiert. |
Diese Tests verwenden festgelegte Versionen und belegen keine Kompatibilität mit allen späteren Veröffentlichungen. guidedog formats zeigt die Nachweise für Reader und Renderer des Programms. Die Reader-Verzeichnisse enthalten weitere Konformitätshinweise.
rst_prolog folgt den anfänglichen bibliografischen Feldern, rst_epilog dem Quelltext. Beide werden nicht in Markdown eingefügt. only und ifconfig behalten ihre Abschnitte bei erfüllter Bedingung. Die Platzierung kann von Sphinx abweichen, wenn ein bedingter Abschnitt die umgebende Gliederungsebene ändert. Abschnittstitel in MyST-eval-rst sind Fehler.
Verweise und Domänen¶
Guidedog implementiert Toctrees, Labels, Glossare, Abschnitts- und Abbildungsnummern sowie Verweise mit ref, doc, numref, term, download, any, keyword, option, envvar und token. Objekte können in Toctrees, Seitenleisten und Seitenübersichten erscheinen.
Die Standard-, Python-, C-, C++-, JavaScript-, reStructuredText- und Mathematikdomänen sind implementiert. Die Odin-Domäne ist eine eigene Erweiterung von Guidedog für Pakete, Deklarationen, Signaturen und generierte API-Seiten. Quelltextbasierte Erkennung und Grenzen beschreibt Odin dokumentieren.
Parameter-, Rückgabe-, Ausnahme- und Variablenfelder bilden strukturierte Beschreibungen. Kanonische Namen werden zu Aliasen für Verweise und Inventare. Python-Standardwerte und Annotationen behalten ihre Quellschreibweise; Sphinx kann sie durch Pythons Unparser neu ausgeben. C++-Deklarationen veröffentlichen Sphinx-kompatible Kennungsversionen und Symbolinventare. Verschachtelungsgrenzen gelten weiterhin. Verschachtelte Klammern werden in linearer Zeit geparst.
numref ersetzt einen Nummernplatzhalter und meldet unnummerierte Ziele. Abschnitte werden in Lesereihenfolge nummeriert. Ein Dokument erhält nur einmal Nummern; ein zweiter nummerierter Toctree meldet den Konflikt. Formatersetzung und Kennungsdetails sind durch Referenztests belegt.
Allgemeiner Index, Modulindex und Suche sind eingebaut. Die Suche findet Wortpräfixe; Sphinx' englisches Stemming wird nicht nachgebildet.
Deklarative Objekttypen ersetzen eine nützliche Klasse von Registrierungen durch Python-Erweiterungen. object_types, crossref_types und directive_aliases beschreiben die Daten. Ein eigenes Python-parse_node wird durch deklarative Namens-, Anzeige- und Programmregeln ersetzt. Nicht darstellbarer Code wird bei der Migration gemeldet. Siehe Objekttypen deklarieren.
Verhalten eingebauter Erweiterungen¶
| Verhalten | Status |
|---|---|
todo, ifconfig, extlinks, autosectionlabel |
Eingebaut. Für fest eingetragene extlinks kann eine passende Rolle vorgeschlagen werden. |
graphviz |
Das eingebundene Graphviz erzeugt statische Zeichnungen. Die Ressourcengrenzen gelten. |
intersphinx |
Lokale und abgerufene Inventare. Windows unterstützt derzeit nur lokale Dateien. |
githubpages |
Eingebaute Veröffentlichungsdateien für statische Sites. |
mathjax und imgmath |
HTML-Formeln verwenden MathJax. Für PDF wird die unterstützte LaTeX-Teilmenge in Typst übersetzt. |
myst_parser |
Die implementierte Markdown-Projektschicht. |
doctest-Direktiven |
Die Inhalte werden angezeigt. Der Projektbuilder führt ihre Tests nicht aus. |
autodoc |
Python-Quelltext wird gelesen, ohne das Paket zu importieren oder auszuführen. |
Quelltextbasiertes autodoc erkennt nicht jedes zur Laufzeit erzeugte Objekt. Kompilierte Module, externe Dekoratoren, berechnete Werte und Ereignishooks haben ausdrückliche Grenzen. Python 3.13 und festgelegte Sphinx-Documenter-Tests dienen als Referenz. Alle Einstellungen und Ausnahmen stehen in Python mit autodoc dokumentieren.
autosummary, napoleon, viewcode und beliebige Python-Erweiterungen liegen außerhalb dieses Weges. Nicht unterstützte Erweiterungen in der Konfiguration werden gemeldet. Unbekannte Direktiven und Rollen werden mit Quellposition gemeldet. Ausgelassene Inhalte müssen vor der Veröffentlichung geprüft werden. Andere Themenamen werden akzeptiert, nutzen aber Guidedogs Theme-Implementierung.
Vertrauen und Ressourcengrenzen¶
Ein normaler Build akzeptiert Raw-HTML und Typst, Vorlagen und Netzwerkinventare des Projekts. Lokale Zugriffe bleiben im Quellverzeichnis und ausdrücklich freigegebenen Wurzeln. Symbolische Links erweitern diese Grenze nicht. Vorlagen, statische Dateien, Includes, Bilder, Schriften und API-Quellen folgen derselben Regel.
Graphviz-Bildressourcen werden relativ zum Dokument aufgelöst und begrenzt. Unterstützte Bilddaten werden in die Zeichnung eingebettet. imagepath und fontpath erweitern die Grenze nicht. Typst läuft mit einer privaten Wurzel, die die lesbaren Verzeichnisse enthält. Buchvorlagen und Präambeln bleiben damit innerhalb der deklarierten Ressourcen.
--untrusted begrenzt Zugriffe auf den Quellordner. Raw-Inhalte, unsichere URLs, externe Ressourcen, Typst-Projektvorlagen und Präambeln werden mit Diagnosen ausgelassen. Inventare und Typst-Pakete werden nicht abgerufen. Graphen mit Ressourcenanforderungen erscheinen mit Warnung als Code. Dieser Modus begrenzt weder Speicher noch Laufzeit des nativen Compilers.
Das Host-Budget beträgt standardmäßig 1 GiB. Speicher wird vor der Zuweisung reserviert. Seitenarbeitsbereiche werden danach freigegeben; Projektgraph und Kataloge bleiben im Speicher und wachsen mit dem Projekt. Lese-Worker koordinieren die Zulassung. Abgelehnte Anforderungen nennen die fehlgeschlagene Operation und Korrekturmöglichkeiten.
--memory=ram stoppt am verwalteten Budget. --memory=disk erlaubt speicherabgebildete temporäre Dateien für verwalteten Arbeitsspeicher. Beibehaltene Host-Daten zählen weiterhin zum RAM-Budget. --disk-budget begrenzt den abgebildeten Speicher; die Richtlinie lässt außerdem eine Plattenreserve. Nichtinteraktive Befehle warten nie auf Antworten. Bekannter freier Spielraum kann mit GUIDEDOG_AVAILABLE_MIB angegeben werden.
--max-depth, --max-nodes und --stack-kib begrenzen die Dokumentverarbeitung. Änderungen machen Lese- und Ausgabecaches ungültig. Tiefe und Stack-Kapazität müssen zusammenpassen. Native Zuweisungen von Graphviz, tree-sitter und Typst liegen außerhalb des Host-Budgets. Für harte Grenzen sind Betriebssystemlimits nötig. Siehe Fehlermeldungen und Speicher und Eigentümerschaft.
Verifikation und reale Projekte¶
tools/sphinxdiff vergleicht 42 festgelegte Sphinx-Testwurzeln: Seiten, Kennungen, Inhaltslinks, Inventare, Nummerierung und Diagnosen. Gespeicherte Ergebnisse und README erklären bewusste Unterschiede, etwa genaue Quellpositionen, stabile Nummern in Lesereihenfolge und ausdrückliche Meldungen für ausgelassene formatspezifische Raw-Inhalte.
Die Remote-Validierung am 1. Oktober 2026 führte saubere und unveränderte HTML- und PDF-Builds für CPython, Django und Flask aus. Alle zwölf waren erfolgreich; Diagnosen und Linkergebnisse entsprachen der Basis. Außerdem bestanden 1,039 Linux-Tests und 94 gezielte AddressSanitizer-Tests.
Diese Projekte enthalten nicht unterstützte Python-Erweiterungskonstrukte. Die Diagnosen bleiben Teil des Nachweises. Ein Exit-Status von null bedeutet nicht, dass alle privaten Direktiven wiedergegeben wurden. Wenn die Veröffentlichung keine Diagnosen erlaubt, verwenden Sie -W.
Historische Messungen und Quellrevisionen stehen in docs/manual/evidence/manuals.md. Der letzte Remote-Prüfbericht liegt in build/review-remote-20261001/report.txt. Die Messungen beschreiben die aufgezeichneten Arbeitslasten, keine allgemeinen Geschwindigkeits- oder Speichergrenzen.