Guidedog / ドキュメント 0.2.0

コマンドラインリファレンス¶

guidedog では、文書プロジェクトの管理、ビルド、プレビュー、翻訳、変換をコマンドラインから行えます。

基本構文¶

guidedog <command> [arguments] [options]
guidedog --version
guidedog --help

終了コード¶

表 6 終了状態¶
終了コード	条件
`0`	成功。すべての処理が完了し、未処理のエラーはありません。
`1`	ビルドまたは変換のエラー。`-W` によって警告をエラーとした場合も含みます。
`2`	コマンドラインの構文、フラグ、オプションに誤りがあります。
`3`	設定した資源の上限に達したか、メモリを確保できません。
`4`	ファイル操作または外部コンパイラーが失敗しました。
`5`	内部エラー。診断に報告方法が記載されます。
`70`	クラッシュ。前回の公開済み出力は残ります。

コマンド一覧¶

表 7 CLI コマンド¶
コマンド	用途
`quickstart [DIR]`	文書プロジェクトを作成し、編集できるテンプレートと設定を配置します。
`build [BUILDER] [DIR]`	指定した出力形式で文書プロジェクトをビルドします。
`serve [DIR]`	ローカルの HTTP プレビューサーバーを起動し、ファイルの変更時に自動で再ビルドします。
`clean [DIR]`	生成した出力とキャッシュを削除します。
`convert INPUT`	単一のファイルまたは標準入力を直接変換します。
`migrate [conf.py]`	Sphinx の `conf.py` を宣言的な `conf.toml` に変換します。
`intl <update\|stat>`	PO 翻訳カタログを更新するか、翻訳の進捗を表示します。
`formats`	組み込まれたリーダー、レンダラー、形式への適合状況を一覧表示します。
`gds <COMMAND>`	Guidedog Discussions の設計記録とライフサイクルを管理します。

guidedog quickstart¶

プロジェクトディレクトリに conf.toml、index.rst、_templates/ のテンプレート、_static/ のスタイルを作成します。

# Interactive prompt
guidedog quickstart docs

# Non-interactive creation with predefined options
guidedog quickstart docs -q -p "My Project" -a "Author Name" -v 1.0 -l en

オプション:

-q: 対話入力を省き、コマンドラインの指定値を使います。
-p, --project NAME: 表示用のプロジェクト名を指定します。
-a, --author NAME: 著者または組織名を指定します。
-v VERSION: 短いバージョン番号を指定します。例: 1.0。
-r RELEASE: 完全なリリース識別子を指定します。例: 1.0.0-rc1。
-l LANGUAGE: 既定の言語を指定します。初期値は en です。
--sep: ルートにソースを置かず、source/ と build/ を分けて作成します。
--suffix EXT: ソース文書の既定の拡張子を指定します。初期値は .rst です。

guidedog build¶

ソースの読み取り、目次ツリーと相互参照の解決、出力の公開をまとめて行います。

# Standard project build
guidedog build html docs
guidedog build pdf docs

# Sphinx-build compatibility syntax
guidedog build -b html docs _build/html
guidedog build -M html docs _build

対応するビルダー:

html: 検索とナビゲーションを備えた HTML サイトを生成します。
dirhtml: dir/index.html のようなディレクトリ形式の URL を生成します。
singlehtml: すべての文書を一つの HTML ページにまとめます。
pdf: Typst で PDF の本を組版します。別名は latex と latexpdf です。
text: 文書ごとにプレーンテキストを生成します。
gettext: 翻訳対象の文字列を GNU gettext の POT テンプレートに抽出します。
dummy: 出力ファイルを作らずに文書ツリーを解析し、参照を解決します。構文確認に使います。

ビルドのオプション:

-a: 更新時刻によらず、すべての出力を書き込みます。
-E: キャッシュを使わず、環境を作り直します。
-W: 警告があればビルドを失敗とします。
--keep-going: -W 使用時も残りの文書を処理し、終了前にすべてのエラーを報告します。
-n: 未解決の相互参照をすべて警告します。
-j N / -j auto: 文書解析の並列数を指定します。auto は CPU コア数に合わせます。
-D name=value: この実行だけ conf.toml の設定を上書きします。例: -D language=de。
-D table.key=value: html_context などの表の設定のキーを一つだけ設定し、ほかのキーは残します。sphinx-build と同じです。
-t TAG: only ディレクティブで使う条件タグを定義します。
-c DIR: conf.toml があるディレクトリを指定します。
-C: conf.toml を読み込まずにビルドします。
-v: 詳細表示。補足情報と処理時間を表示します。
-q: 警告とエラーだけを表示します。
--color=always|never|auto: 端末の ANSI 色表示を指定します。
--diagnostics=json: 機械処理用の JSON 診断を標準エラー出力に書き込みます。
--budget=MIB: プロジェクトホストが保持するメモリの上限を指定します。初期値は 1024 MiB です。
--memory=ram|disk: メモリ予算を使い切ったときの動作を指定します。
--untrusted: 生の埋め込みマークアップを省き、ネットワーク取得を無効にします。機能を制限する方針であり、プロセスのサンドボックスではありません。

guidedog serve¶

ローカルの HTTP サーバーとファイル監視を起動します。ソース、テンプレート、素材の変更時に再ビルドし、ブラウザーを更新します。

# Serve current project on default port (8000)
guidedog serve docs

# Serve on custom port and host
guidedog serve docs --port 9000 --host 0.0.0.0

オプション:

-p, --port PORT: 待ち受けポート。初期値は 8000 です。
--host HOST: バインドする IP アドレス。初期値は 127.0.0.1 です。

guidedog clean¶

ビルドディレクトリと環境のキャッシュを削除します。

guidedog clean docs

guidedog convert¶

プロジェクトや設定ファイルを使わず、ファイルまたは標準入力を変換します。

# Convert reStructuredText to HTML
guidedog convert guide.rst --output guide.html

# Convert Markdown to PDF
guidedog convert guide.md --to pdf --output guide.pdf

# Stream conversion from standard input to standard output
cat document.md | guidedog convert - --from commonmark --to html --output -

オプション:

-o, --output FILE: 出力先のパス。- は標準出力です。
--to FORMAT: 出力形式は html、pdf、text。ファイル名からも推定できます。
--from FORMAT: 入力リーダーは rst、commonmark、myst、typst。拡張子からも推定できます。
--force: 確認せずに既存の出力ファイルを上書きします。
--strict: 警告があれば失敗とします。
--raw=allow|omit: 埋め込みの生コードの扱い。初期値は omit です。
--emit-typst FILE: 生成した中間 Typst ソースを別のファイルに保存します。

guidedog migrate¶

Sphinx の Python 設定ファイル conf.py を宣言的な conf.toml に変換します。

# Convert conf.py in-place
guidedog migrate docs/conf.py

# Output to a specific file
guidedog migrate docs/conf.py -o docs/conf.toml --force

オプション:

-o FILE: 指定のパスに保存します。- は標準出力です。
--force: 既存の conf.toml を上書きします。

guidedog intl¶

多言語文書の翻訳カタログを管理します。

# Step 1: Extract POT templates
guidedog build gettext docs

# Step 2: Create or update language PO catalogs
guidedog intl update -l de -l fr docs

# Check translation completion percentages
guidedog intl stat -l de docs

intl update のオプション:

-l, --language LANG: 対象言語のコード。複数回指定できます。
-p, --pot-dir DIR: 抽出済み POT テンプレートのパスを指定します。

guidedog formats¶

組み込まれたリーダー、レンダラー、構文ハイライト機能、仕様テストの結果を表示します。

guidedog formats

guidedog gds¶

Guidedog Discussions のアーキテクチャ設計提案（RFC）を管理します。

guidedog gds new "Feature Title" --author="Name"
guidedog gds list --state=prediscussion
guidedog gds show 0003
guidedog gds promote 0003 --dry-run
guidedog gds state 0003 --to=accepted --reason="Consensus reached"
guidedog gds index
guidedog gds check --render
guidedog gds recover --rollback