Guidedog / Documentation 0.2.0

Configuration reference¶

Every Guidedog documentation project is configured using conf.toml, located at the project root directory. Guidedog reads configuration as declarative TOML data and does not execute arbitrary code.

Many configuration keys correspond directly to Sphinx’s conf.py variables, allowing straightforward migration with guidedog migrate conf.py.

Minimal configuration¶

A project requires only basic metadata. Default values are applied for omitted keys:

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"

Project metadata¶

Table 8 Metadata options¶
Key	Type	Default	Description
`project`	string	`"Python"`	The human-readable name of the project.
`author`	string	`""`	Author or organization name.
`copyright`	string	`""`	Copyright notice displayed in page footers.
`version`	string	`""`	The short project version (e.g. `"1.0"`).
`release`	string	`""`	The full version string, including alpha/beta identifiers (e.g. `"1.0.0b1"`).
`language`	string	`"en"`	ISO language code (e.g. `"de"`, `"zh_CN"`) for typography, hyphenation, and translations.
`today`	string	`""`	Custom date text; if omitted, current time is formatted with `today_fmt`.
`today_fmt`	string	`""`	Format string for document dates.

General options¶

Table 9 Discovery and parsing options¶
Key	Type	Default	Description
`root_doc`	string	`"index"`	The document that serves as the root table of contents.
`source_suffix`	array	`[".rst"]`	File extensions recognized as documentation source files.
`exclude_patterns`	array	`[]`	Directory and file glob patterns excluded from source discovery.
`include_roots`	array	`[]`	External directory roots allowed for source inclusion.
`templates_path`	array	`[]`	Directories containing HTML and PDF templates, searched before built-ins.
`extensions`	array	`[]`	Supported built-in Sphinx extensions to enable (e.g. `"sphinx.ext.autodoc"`).
`primary_domain`	string	`"py"`	The default domain used for unqualified directives and roles (e.g. `"py"`, `"c"`, `"odin"`).
`highlight_language`	string	`"default"`	Default language for code blocks when unspecified.
`pygments_style`	string	`""`	Pygments syntax highlighting style for light themes.
`pygments_dark_style`	string	`""`	Syntax highlighting style used when dark mode is active.
`smartquotes`	boolean	`true`	Automatically transforms straight quotes and dashes into typographer’s punctuation.
`rst_prolog`	string	`""`	ReStructuredText snippet prepended to every parsed document.
`rst_epilog`	string	`""`	ReStructuredText snippet appended to every parsed document.

Numbering and mathematics¶

Table 10 Numbering options¶
Key	Type	Default	Description
`numfig`	boolean	`false`	When true, automatically numbers figures, tables, and code listings.
`numfig_secnum_depth`	integer	`1`	Heading depth included in figure numbers (e.g. `1` produces `Fig. 2.1`).
`numfig_format`	table	see below	Numbering prefix formats for `"figure"`, `"table"`, and `"code-block"`.
`math_number_all`	boolean	`false`	When true, numbers every display equation automatically.
`math_eqref_format`	string	`"({number})"`	Format string for equation references made with `:eq:`.
`mathjax_path`	string	URL	CDN or local path to MathJax JavaScript bundle.

Default numfig_format values:

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

Diagnostics and strictness¶

Table 11 Diagnostic options¶
Key	Type	Default	Description
`nitpicky`	boolean	`false`	Warns on all unresolved cross-references and broken targets.
`nitpick_ignore`	array	`[]`	Array of `[type, target]` pairs exempted from nitpicky warnings.
`suppress_warnings`	array	`[]`	Warning category codes that should not be reported.
`keep_warnings`	boolean	`false`	Includes warnings directly in published document output.

HTML output options¶

Table 12 HTML options¶
Key	Type	Default	Description
`html_theme`	string	`"guidedog"`	Theme used for HTML generation.
`html_theme_options`	table	`{}`	Key-value options passed to the HTML theme.
`html_title`	string	derived	Page title displayed in browser window tabs.
`html_short_title`	string	derived	Shorter title used in navigation breadcrumbs.
`html_logo`	string	`""`	Path to project logo image relative to source directory.
`html_favicon`	string	`""`	Path to favicon file.
`html_static_path`	array	`[]`	Directories copied to the output’s `_static/` directory.
`html_extra_path`	array	`[]`	Directories copied directly to the output root without transformation.
`html_css_files`	array	`[]`	Custom CSS filenames loaded by HTML pages.
`html_js_files`	array	`[]`	Custom JavaScript filenames loaded by HTML pages.
`html_permalinks`	boolean	`true`	Adds paragraph and section anchor permalinks.
`html_permalinks_icon`	string	`"¶"`	Glyph or text used for permalink anchors.
`html_baseurl`	string	`""`	Canonical base URL used for sitemaps and metadata.
`html_context`	table	`{}`	Custom dictionary of variables exposed to Jinja templates.
`html_additional_pages`	table	`{}`	Custom pages to render: `{ "page_name" = "template.html" }`.

PDF and Typst options¶

Table 13 PDF options¶
Key	Type	Default	Description
`pdf_paper_size`	string	`"a4"`	Paper format: `"a4"` or `"us-letter"`.
`pdf_logo`	string	`""`	Logo image path for book cover pages.
`pdf_toplevel_sectioning`	string	`"chapter"`	Section level mapped to book divisions: `"chapter"` or `"part"`.
`pdf_show_urls`	string	`"no"`	URL display policy in print: `"no"`, `"inline"`, or `"footnote"`.
`pdf_preamble`	string	`""`	Raw Typst source injected into generated document headers.
`pdf_font_paths`	array	`[]`	Additional directory paths searched for custom OTF/TTF fonts.
`pdf_packages`	string	`"download"`	Package resolution strategy: `"download"` or `"offline"`.
`typst`	string	`"typst"`	System binary name or absolute path to Typst CLI.

Defining PDF books¶

The [[pdf_documents]] table defines one or more books built from the project:

[[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 options¶

Table 14 MyST Markdown options¶
Key	Type	Default	Description
`myst_enable_extensions`	array	`["dollarmath"]`	Syntax extensions: `"colon_fence"`, `"deflist"`, `"dollarmath"`, `"fieldlist"`, `"tasklist"`, `"substitution"`.
`myst_heading_anchors`	integer	`0`	Heading level depth that automatically generates slug anchor targets (`0` disables).
`myst_substitutions`	table	`{}`	Variable substitutions available in Markdown documents: `{key = "value"}`.
`myst_url_schemes`	array	`["http", ...]`	Recognized URI schemes treated as external links.
`myst_commonmark_only`	boolean	`false`	Restricts parser strictly to CommonMark syntax without MyST extensions.

Intersphinx options¶

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", ""]]

See Linking to other projects for full workflow instructions.

Python autodoc options¶

Table 15 Autodoc options¶
Key	Type	Default	Description
`autodoc_source_paths`	array	`[]`	Directories added to Python module search path for static analysis.
`autoclass_content`	string	`"class"`	Docstring source for classes: `"class"`, `"init"`, or `"both"`.
`autodoc_member_order`	string	`"alphabetical"`	Member ordering: `"alphabetical"`, `"bysource"`, or `"groupwise"`.
`autodoc_typehints`	string	`"signature"`	Type hint placement: `"signature"`, `"description"`, or `"none"`.
`autodoc_default_options`	table	`{}`	Default directive options applied to all `auto*` directives.

See Documenting Python with autodoc for complete discovery rules.

Odin API documentation options¶

Table 16 Odin domain options¶
Key	Type	Default	Description
`odin_autoapi_dirs`	array	`[]`	Source directories scanned for Odin packages.
`odin_autoapi_root`	string	`"api"`	Destination subfolder for generated Odin API documentation.
`odin_autoapi_options`	array	`["members", "undoc-members"]`	Member inclusion filters.
`odin_autoapi_member_order`	string	`"source"`	Member ordering: `"source"` or `"alphabetical"`.

See Documenting Odin for complete Odin domain usage.

Internationalization options¶

Table 17 i18n options¶
Key	Type	Default	Description
`locale_dirs`	array	`["locales"]`	Directories searched for gettext message catalogs.
`gettext_compact`	boolean	`true`	Consolidates subdocument messages into one catalog per directory.
`gettext_uuid`	boolean	`false`	Emits stable UUIDs in POT message headers.
`gettext_auto_build`	boolean	`true`	Compiles `.po` files into binary `.mo` catalogs during the build.
`figure_language_filename`	string	`"{root}.{language}{ext}"`	Filename template for localized image selection.

See Internationalization for translation instructions.