Guidedog / ドキュメント
0.2.0
プロジェクトの仕組み¶
プロジェクトルートは conf.toml のあるディレクトリー。root_doc は読む順序の起点。Guidedog は文書を探索・読み取り、関係を解決して完全な世代を公開する。
文書とリソース¶
拡張子でリーダーを選ぶ。RST とプロジェクト Markdown は同じグラフを使う。画像とダウンロードはリソースで、文書が使うものをコピーする。テーマ資産は html_static_path。インクルードはソースまたは include_roots 内に限る。
独立したプロジェクト¶
マニュアルと設計記録は読者も読む順も違うため分ける。それぞれ設定、テンプレート、キャッシュ、出力を持つ。このリポジトリの docs/manual と docs/gds がその例だ。
差分ビルド¶
各出力の入力と参照結果を記録する。ソース変更は再読、依存変更は利用側の無効化、テンプレート変更は全ページに影響し得る。未変更文書は保存したオブジェクトから読める。
キャッシュは以前のビルドの証拠で、真実の源ではない。-E は保存環境を次回に使わず、-a は全出力を書く。解く問題は異なる。
\[\text{再利用可能} = \text{入力が同じ} \land \text{参照結果が同じ} \land \text{出力が存在する}\]
テンプレートの時刻もページへの入力だ。現在の分を表示するページは原文不変でも変わる。固定時刻には SOURCE_DATE_EPOCH を使う。
公開¶
変更は同階層のステージングに書く。完成とファイル・記録の永続化後に世代を切り替える。読者には完全な旧版か新版を見せ、中断コミットは次回処理する。設計と証明責務は 完全な世代を公開する。