Ein Sphinx-Projekt migrieren¶
Guidedog folgt dem Projektaufbau von Sphinx und vielen seiner Einstellungsnamen. conf.py und Python-Erweiterungen werden nicht ausgeführt. Die Migration beginnt damit, Daten von ausführbarer Konfiguration zu trennen.
guidedog migrate path/to/conf.py
guidedog build html path/to/docs --diagnostics=json
migrate liest literale Einstellungen und schreibt conf.toml. Berechnete Werte, die eine menschliche Entscheidung erfordern, werden gemeldet. Es importiert das Projekt nicht und führt kein Python aus. Prüfen Sie das Ergebnis, bevor Sie es als gleichwertig behandeln.
In drei Schritten vorgehen¶
- Korrigieren Sie den Dokumentgraphen. Prüfen Sie Wurzel, Suffixe, Ausschlüsse und Includes.
- Korrigieren Sie die Verweise. Prüfen Sie Domänen, Inventare und eigene Objekttypen.
- Korrigieren Sie die Darstellung. Prüfen Sie Vorlagen, Diagramme, Mathematik und beide Ausgaben.
Eine unbekannte Direktive kann aus einer projektspezifischen Erweiterung stammen. Ein erfolgreicher HTML-Build beweist nicht, dass deren Semantik nachgebildet wurde. Lesen Sie die Diagnosen. Entscheiden Sie dann zwischen Ersatz, unterstütztem Alias oder einer dokumentierten Einschränkung.
Unterstützte Funktionen und Nachweise zu CPython, Django und Flask stehen in Kompatibilität mit Sphinx. Deklarative eigene Objekte beschreibt Objekttypen deklarieren.