このページの内容

Guidedog / ドキュメント 0.2.0

Sphinx プロジェクトの移行

Guidedog は Sphinx のプロジェクト構造と多くの設定名に従うが、conf.py や Python 拡張は実行しない。移行はデータと実行可能な設定を分けるところから始める。

guidedog migrate path/to/conf.py
guidedog build html path/to/docs --diagnostics=json

migrate はリテラルの設定を読み、conf.toml に書く。計算で得る値は人の判断が必要として報告する。値を調べるためにプロジェクトをインポートしたり Python を実行したりしない。同等と見なす前に生成した設定を確認する。

3 段階で進める

1. まず文書グラフを正しくします。ルート、拡張子、除外、include を確認します。
2. 次に参照を正しくします。ドメイン、インベントリ、独自のオブジェクト型を確認します。
3. 最後に表示を正しくします。テンプレート、図、数式、両方の出力を確認します。

未知のディレクティブは独自拡張のものかもしれない。HTML ビルドの成功だけでは、その意味まで再現したとは言えない。診断を読み、置き換えるか、対応するエイリアスを設定するか、制限を明記して残すかを判断する。

対応範囲と CPython、Django、Flask の検証結果は Sphinx との互換性 を参照。宣言的なカスタムオブジェクトは オブジェクト型の宣言 を参照。