このページの内容

Guidedog / ドキュメント 0.2.0

Sphinx との互換性

作者の移行に役立つ部分では Sphinx に従い、機能ごとに互換性を検証します。Python の設定や任意の Python 拡張は実行しません。ビルドの成功は、そのビルドが完了した証拠であり、完全な同等性の証明ではありません。

プロジェクトと公開

表 20 プロジェクトの操作

操作	実装済みの動作
プロジェクト構成とビルドオプション	Sphinx 形式のソース・出力ディレクトリとオプション：-a -E -W -n -D -t -j -b -M -c -C。
設定	Sphinx でおなじみの設定名を TOML データとして記述します。移行時はリテラルを変換し、計算が必要な値を報告します。
HTML ビルダー	html、dirhtml、singlehtml に対応します。単一ページのアンカーには文書名を含めます。
その他のビルダー	text、gettext、dummy に対応します。pdf は Typst を使い、latex と latexpdf も同じ経路を選びます。
テンプレート	Guidedog の Jinja 実装、型を保持する html_context、レイアウトの継承、追加ページ。
差分ビルド	ソース、依存関係、テンプレート、設定、参照検索の変更で、関連する出力が無効になります。
公開	完全な世代を一度に公開します。ビルドに失敗した場合は前の公開済み世代を保持します。

-D の真偽値には true と false、または 1 と 0 を使えます。index がなく contents があるプロジェクトでは、警告付きで contents をルートにできます。追加テンプレートページは dirhtml でもサイトのルートに置きます。詳しい規約は テンプレート を参照してください。

変更のないページでも診断を再表示するため、-W は新規ビルドと変更のないビルドで同じ意味を持ちます。削除した文書のページは取り除きます。公開には復旧可能なジャーナルを使い、中断したコミットは次のビルドで処理します。不変条件とプラットフォーム上の制約は 完全な世代を公開する を参照してください。

epub、man、texinfo、linkcheck、doctest、coverage、changes ビルダーはありません。指定すると修正方法を報告します。リポジトリの tools/linkcheck は独立した検証ツールです。

ソース形式

表 21 固定版による適合性の検証

リーダー	検証結果と制約
reStructuredText	98 個のコーパスソースで、比較対象の Docutils の木と識別子が一致します。ソース位置と一部の内部管理属性は比較から除外しています。
CommonMark 0.31.2	仕様の例 652 件がすべて通ります。
MyST 0.16.1 reference	リーダーのテストケース 218 件中 215 件、Sphinx のビルドケース 10 件中 8 件が一致します。残る差分は記録しています。

固定版でのテストであり、以後のすべての版との互換性を示すものではありません。guidedog formats で実行ファイルのリーダーとレンダラーの検証結果を確認できます。各リーダーのディレクトリにも適合性の注記があります。

rst_prolog は冒頭の書誌フィールドの後に、rst_epilog はソースの後に挿入します。Markdown にはどちらも挿入しません。only と ifconfig は条件を満たす節を残します。条件付きの節が周囲の階層を変える場合、配置が Sphinx と異なることがあります。MyST の eval-rst 内の節見出しはエラーです。

参照とドメイン

Guidedog は toctree、ラベル、用語集、節と図の番号付け、および ref、doc、numref、term、download、any、keyword、option、envvar、token 参照を実装しています。オブジェクトは目次ツリー、サイドバー、ページのアウトラインに表示できます。

標準、Python、C、C++、JavaScript、reStructuredText、数学のドメインを実装しています。Odin ドメインは Guidedog 独自の拡張で、パッケージ、宣言、シグネチャ、生成 API ページを記述します。ソースだけを使う探索の仕組みと制約は Odin の文書化 を参照してください。

引数、戻り値、例外、変数のフィールドを構造化した説明にまとめます。正規名は参照とインベントリの別名になります。Python の既定値と注釈はソースの表記を保ちます。Sphinx は Python の unparser で再出力する場合があります。C++ 宣言は Sphinx 互換の識別子バージョンとシンボル一覧を公開します。入れ子の深さには制限があり、入れ子の括弧は線形時間で解析します。

numref は番号のプレースホルダーを 1 つ置換し、番号のない参照先を報告します。節は読む順に番号を付けます。各文書は一度だけ番号を付け、2 つ目の番号付き toctree は競合を報告します。書式の置換と識別子の詳細は参照テストを確認してください。

総合索引、モジュール索引、検索は組み込みです。検索は単語の前方一致を使い、Sphinx の英語ステミングは再現しません。

宣言的なオブジェクト型で、よく使われる Python 拡張登録を置き換えられます。object_types、crossref_types、directive_aliases がデータを記述します。独自の Python parse_node は名前・表示・プログラムの宣言規則に置き換えます。表せないコードは移行時に報告します。オブジェクト型の宣言 を参照してください。

組み込み拡張の動作

表 22 拡張の範囲

動作	状態
todo, ifconfig, extlinks, autosectionlabel	組み込みです。直書きした extlinks のリンクにはロールへの置換を提案できます。
graphviz	リンクした Graphviz が静的な図を生成します。リソースの範囲制限を適用します。
intersphinx	ローカルと取得済みのインベントリに対応します。Windows は現在ローカルファイルのみ対応です。
githubpages	静的サイト用の公開ファイルを組み込みで生成します。
mathjax と imgmath	HTML の数式は MathJax を使います。PDF は対応する LaTeX の部分集合を Typst に変換します。
myst_parser	実装済みのプロジェクト用 Markdown 層です。
doctest ディレクティブ	内容は表示しますが、プロジェクトビルダーはテストを実行しません。
autodoc	パッケージをインポート・実行せず、Python ソースを読みます。

ソースベースの autodoc は、実行時に作られるすべてのオブジェクトを検出できません。コンパイル済みモジュール、外部デコレータ、計算された値、拡張のイベントフックには明確な制約があります。Python 3.13 と固定版の Sphinx 文書生成テストを基準としています。設定と例外の全体は autodoc による Python のドキュメント作成 を参照してください。

autosummary、napoleon、viewcode と任意の Python 拡張はこの経路の対象外です。未対応の拡張を設定すると報告します。不明なディレクティブやロールはソース位置付きで報告します。省かれた内容は公開前に必ず確認してください。他のテーマ名も受け付けますが、Guidedog のテーマ実装を使います。

信頼とリソース制限

通常のビルドはプロジェクトの raw HTML・Typst、テンプレート、ネットワーク上のインベントリを許可します。ローカル読み取りはソースディレクトリと明示した共有ルート内に限ります。シンボリックリンクで範囲を広げることはできません。テンプレート、静的ファイル、include、画像、フォント、API ソースも同じ規則に従います。

Graphviz の画像リソースは文書を基準に解決し、読み取り範囲を制限します。対応する画像データは図に埋め込みます。imagepath と fontpath は範囲を広げません。Typst は読み取り可能なディレクトリを含む専用ルートで実行し、本のテンプレートとプリアンブルを宣言したリソース内に限定します。

--untrusted は読み取り範囲をソースディレクトリに限定します。raw コンテンツ、安全でない URL、外部リソース、プロジェクトの Typst テンプレートとプリアンブルを診断付きで省きます。インベントリや Typst パッケージは取得しません。リソースを読むグラフはコードとして表示し、警告します。このモードはネイティブコンパイラのメモリや実行時間を制限しません。

ホストの予算は既定で 1 GiB です。確保前に容量を予約します。ページの作業領域は使用後に解放しますが、保持するプロジェクトグラフとカタログは規模に応じてメモリを使います。読み取りワーカーが処理の受け入れを調整します。要求を拒否した場合は、失敗した操作と修正方法を報告します。

--memory=ram は管理予算に達すると停止します。--memory=disk は管理対象の作業ストレージにメモリマップした一時ファイルを許可します。保持するホストストレージは RAM 予算に含まれます。--disk-budget はマップ領域を制限し、ディスクの余裕も残します。非対話コマンドは回答を待ちません。既知の空き容量は GUIDEDOG_AVAILABLE_MIB で指定できます。

--max-depth、--max-nodes、--stack-kib は文書処理を制限します。値を変更すると読み取りと出力のキャッシュを無効にします。深さとスタック容量は整合させてください。ネイティブ Graphviz、tree-sitter、Typst の確保はホスト予算の対象外です。厳密な上限には OS の制限を使います。エラーメッセージ と メモリと所有権 を参照してください。

検証と実際のプロジェクト

tools/sphinxdiff は固定版の Sphinx テストルート 42 件で、ページ、識別子、本文リンク、インベントリ、番号付け、診断を比較します。保存した結果と README に意図的な差分を説明しています。正確なソース位置、安定した読み順の番号、対象形式専用の raw コンテンツを省いた際の明示的な報告などです。

2026 年 10 月 1 日のリモート検証では CPython、Django、Flask の新規ビルドと変更なしの HTML・PDF ビルドを実施しました。12 件すべてが成功し、診断とリンク結果は基準と一致しました。Linux テスト 1,039 件と対象を絞った AddressSanitizer テスト 94 件も通りました。

これらのプロジェクトには未対応の Python 拡張構文があり、その診断も検証結果の一部です。終了ステータスがゼロでも、独自のディレクティブがすべて再現されたとは限りません。診断を出さずに公開する必要がある場合は -W を使ってください。

過去の測定値とソースのリビジョンは docs/manual/evidence/manuals.md にあります。最新のリモートレビューは build/review-remote-20261001/report.txt です。測定値は記録した負荷を表しており、一般的な速度やメモリの上限ではありません。