Guidedog / ドキュメント 0.2.0

設定リファレンス¶

Guidedog の設定はプロジェクトルートの conf.toml に記述します。宣言的な TOML データとして読み込まれ、任意のコードは実行されません。

多くの設定キーは Sphinx の conf.py 変数に対応し、guidedog migrate conf.py で移行できます。

最小構成¶

基本情報だけでもプロジェクトを作れます。省略した設定には初期値が使われます。

project = "Field Notes"
author = "Your Name"
version = "1.0"
release = "1.0.0"
language = "en"
root_doc = "index"
source_suffix = [".rst", ".md"]
templates_path = ["_templates"]
html_static_path = ["_static"]
pdf_paper_size = "a4"

プロジェクト情報¶

表 8 メタデータの設定¶
キー	型	初期値	説明
`project`	文字列	`"Python"`	表示用のプロジェクト名。
`author`	文字列	`""`	著者または組織名。
`copyright`	文字列	`""`	フッターに表示する著作権表記。
`version`	文字列	`""`	短いバージョン番号。例: `"1.0"`。
`release`	文字列	`""`	完全なバージョン番号。alpha や beta の識別子も含みます。例: `"1.0.0b1"`。
`language`	文字列	`"en"`	組版、ハイフネーション、翻訳に使う ISO 言語コード。例: `"de"`、`"zh_CN"`。
`today`	文字列	`""`	日付の表示文字列。未指定なら現在の日付を `today_fmt` で整形します。
`today_fmt`	文字列	`""`	文書の日付に使う書式文字列。

一般設定¶

表 9 検出と解析の設定¶
キー	型	初期値	説明
`root_doc`	文字列	`"index"`	目次のルートとなる文書。
`source_suffix`	配列	`[".rst"]`	文書ソースとして認識する拡張子。
`exclude_patterns`	配列	`[]`	ソース検出から除外するファイルやディレクトリの glob パターン。
`include_roots`	配列	`[]`	外部ファイルの取り込みを許可するルートディレクトリ。
`templates_path`	配列	`[]`	HTML と PDF のテンプレートディレクトリ。組み込みより先に検索します。
`extensions`	配列	`[]`	有効にする組み込みの Sphinx 拡張。例: `"sphinx.ext.autodoc"`。
`primary_domain`	文字列	`"py"`	接頭辞のないディレクティブやロールに使う既定のドメイン。例: `"py"`、`"c"`、`"odin"`。
`highlight_language`	文字列	`"default"`	コードブロックで言語を省略したときの初期値。
`pygments_style`	文字列	`""`	明るいテーマで使う Pygments のハイライトスタイル。
`pygments_dark_style`	文字列	`""`	暗いテーマで使う構文ハイライトスタイル。
`smartquotes`	真偽値	`true`	直線の引用符やハイフンを組版用の句読点に変換します。
`rst_prolog`	文字列	`""`	各文書の先頭に追加する reStructuredText 断片。
`rst_epilog`	文字列	`""`	各文書の末尾に追加する reStructuredText 断片。

番号と数式¶

表 10 番号の設定¶
キー	型	初期値	説明
`numfig`	真偽値	`false`	図、表、コードに自動で番号を付けます。
`numfig_secnum_depth`	整数	`1`	図番号に含める見出しの深さ。`1` なら `Fig. 2.1` のようになります。
`numfig_format`	テーブル	下記参照	`"figure"`、`"table"`、`"code-block"` の番号書式。
`math_number_all`	真偽値	`false`	すべての独立行数式に自動で番号を付けます。
`math_eqref_format`	文字列	`"({number})"`	`:eq:` による数式参照の書式。
`mathjax_path`	文字列	URL	MathJax JavaScript の CDN URL またはローカルパス。

numfig_format の初期値:

[numfig_format]
figure = "Fig. %s"
table = "Table %s"
code-block = "Listing %s"
section = "Section %s"

診断と厳密な検査¶

表 11 診断の設定¶
キー	型	初期値	説明
`nitpicky`	真偽値	`false`	未解決の相互参照やリンク先を警告します。
`nitpick_ignore`	配列	`[]`	警告を除外する `[type, target]` の配列。
`suppress_warnings`	配列	`[]`	表示しない警告カテゴリのコード。
`keep_warnings`	真偽値	`false`	公開文書の本文に警告を含めます。

HTML 出力の設定¶

表 12 HTML の設定¶
キー	型	初期値	説明
`html_theme`	文字列	`"guidedog"`	HTML 生成に使うテーマ。
`html_theme_options`	テーブル	`{}`	HTML テーマに渡すキーと値。
`html_title`	文字列	自動生成	ブラウザーのタブに表示するタイトル。
`html_short_title`	文字列	自動生成	パンくずナビゲーションの短いタイトル。
`html_logo`	文字列	`""`	ソースディレクトリからのロゴ画像の相対パス。
`html_favicon`	文字列	`""`	ファビコンのパス。
`html_static_path`	配列	`[]`	出力の `_static/` にコピーするディレクトリ。
`html_extra_path`	配列	`[]`	変換せずに出力ルートにコピーするディレクトリ。
`html_css_files`	配列	`[]`	HTML ページが読み込む追加 CSS のファイル名。
`html_js_files`	配列	`[]`	HTML ページが読み込む追加 JavaScript のファイル名。
`html_permalinks`	真偽値	`true`	段落と見出しに固定リンクを付けます。
`html_permalinks_icon`	文字列	`"¶"`	固定リンクに使う記号や文字。
`html_baseurl`	文字列	`""`	サイトマップとメタデータの正規の基準 URL。
`html_context`	テーブル	`{}`	Jinja テンプレートに渡す追加変数の辞書。
`html_additional_pages`	テーブル	`{}`	追加ページ: `{ "page_name" = "template.html" }`。

PDF と Typst の設定¶

表 13 PDF の設定¶
キー	型	初期値	説明
`pdf_paper_size`	文字列	`"a4"`	用紙サイズ: `"a4"` または `"us-letter"`。
`pdf_logo`	文字列	`""`	表紙に使うロゴ画像のパス。
`pdf_toplevel_sectioning`	文字列	`"chapter"`	本の最上位の区分: `"chapter"` または `"part"`。
`pdf_show_urls`	文字列	`"no"`	印刷版の URL 表示: `"no"`、`"inline"`、`"footnote"`。
`pdf_preamble`	文字列	`""`	生成文書の先頭に挿入する Typst の生コード。
`pdf_font_paths`	配列	`[]`	追加の OTF/TTF フォントを探すディレクトリ。
`pdf_packages`	文字列	`"download"`	パッケージ解決の方針: `"download"` または `"offline"`。
`typst`	文字列	`"typst"`	システムの Typst CLI の名前または絶対パス。

PDF の本を定義する¶

[[pdf_documents]] テーブルで、このプロジェクトから作る本を一冊以上定義します。

[[pdf_documents]]
root = "index"
file = "guide.pdf"
title = "Field Notes Complete Guide"
author = "Author Name"

[[pdf_documents]]
root = "reference/index"
file = "reference.pdf"
title = "Field Notes Reference"
author = "Author Name"

MyST Markdown の設定¶

表 14 MyST Markdown の設定¶
キー	型	初期値	説明
`myst_enable_extensions`	配列	`["dollarmath"]`	構文拡張: `"colon_fence"`、`"deflist"`、`"dollarmath"`、`"fieldlist"`、`"tasklist"`、`"substitution"`。
`myst_heading_anchors`	整数	`0`	見出しからアンカーを作る深さ。`0` で無効になります。
`myst_substitutions`	テーブル	`{}`	Markdown 文書で使う変数の置換。例: `{key = "value"}`。
`myst_url_schemes`	配列	`["http", ...]`	外部リンクとして認識する URI スキーム。
`myst_commonmark_only`	真偽値	`false`	MyST 拡張を使わず、CommonMark の構文だけを解析します。

Intersphinx の設定¶

extensions = ["sphinx.ext.intersphinx"]
intersphinx_cache_limit = 5
intersphinx_timeout = 30

[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]

詳しい手順は他のプロジェクトへのリンクを参照してください。

Python autodoc の設定¶

表 15 Autodoc の設定¶
キー	型	初期値	説明
`autodoc_source_paths`	配列	`[]`	静的解析で Python モジュールを探すディレクトリ。
`autoclass_content`	文字列	`"class"`	クラスの docstring の取得元: `"class"`、`"init"`、`"both"`。
`autodoc_member_order`	文字列	`"alphabetical"`	メンバーの並び順: `"alphabetical"`、`"bysource"`、`"groupwise"`。
`autodoc_typehints`	文字列	`"signature"`	型ヒントの表示位置: `"signature"`、`"description"`、`"none"`。
`autodoc_default_options`	テーブル	`{}`	すべての `auto*` ディレクティブに適用する既定の設定。

検出規則の詳細は autodoc による Python のドキュメント作成を参照してください。

Odin API 文書の設定¶

表 16 Odin ドメインの設定¶
キー	型	初期値	説明
`odin_autoapi_dirs`	配列	`[]`	Odin パッケージを探すソースディレクトリ。
`odin_autoapi_root`	文字列	`"api"`	生成する Odin API 文書の出力サブディレクトリ。
`odin_autoapi_options`	配列	`["members", "undoc-members"]`	含めるメンバーのフィルター。
`odin_autoapi_member_order`	文字列	`"source"`	メンバーの並び順: `"source"` または `"alphabetical"`。

Odin ドメインの詳しい使い方は Odin の文書化を参照してください。

国際化の設定¶

表 17 i18n の設定¶
キー	型	初期値	説明
`locale_dirs`	配列	`["locales"]`	gettext カタログを探すディレクトリ。
`gettext_compact`	真偽値	`true`	同じディレクトリの文書を一つのカタログにまとめます。
`gettext_uuid`	真偽値	`false`	POT メッセージに安定した UUID を付けます。
`gettext_auto_build`	真偽値	`true`	ビルド時に `.po` をバイナリの `.mo` にコンパイルします。
`figure_language_filename`	文字列	`"{root}.{language}{ext}"`	言語別の画像を選ぶファイル名テンプレート。

翻訳手順は国際化を参照してください。