Guidedog / ドキュメント 0.2.0

この文書の保守¶

Guidedog のプロジェクトは docs/manual、docs/api、docs/gds の三つ。マニュアルと GDS は guidedog quickstart で作った。生成されたテンプレートを直接編集する。設計記録はマニュアルの目次に入れない。

マニュアルのビルド¶

リポジトリのルートで実行します。

build/guidedog build html docs/manual -j auto -W
build/guidedog build pdf docs/manual -W
build/guidedog serve docs/manual

マニュアルの目次には完全な Odin API リファレンスも入る。PDF コマンドは説明と宣言をリンクで結ぶ一冊の本を作る。マニュアルと独立した API プロジェクトはどちらも lib/ から生成するため、複製した原稿を同期する必要はない。

API プロジェクトだけをビルドするには、次を実行します。

build/guidedog build html docs/api -W
build/guidedog build pdf docs/api -W

議論文書のビルドと検査¶

build/guidedog gds index
build/guidedog gds check
build/guidedog gds build --target=both

GDS CLI はメタデータ、番号、状態、復旧を管理する。RST の公開処理はプロジェクトエンジンを呼び、完全な HTML サイトと記録ごとの PDF を作る。セレクターが制限するのは PDF だけで、HTML は完全なカタログを持つ一貫したサイトのまま。選択した PDF のプレビューは _build/selected/<artifact>/pdf を使い、_build/pdf の全体カタログを保つ。

build/guidedog gds build guidedoc-odin --target=pdf
build/guidedog build html docs/gds -W
build/guidedog build pdf docs/gds -W

通常のプロジェクトコマンドも使える。GDS は独自の conf.toml と _build を持つ。執筆手順は docs/gds/workflow.rst を参照。

公開する前に¶

リンクと診断を確認し、幅広い表やコードブロックを調べる。組版を変更したら PDF を画像化して確認する。HTML はデスクトップとスマートフォンの幅、ライトとダークの両方で試す。数式と図がネット接続なしでも動くことを確かめる。エンジンの変更には関連するライブラリーと統合テストを実行する。