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: .. code-block:: toml 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 ---------------- .. list-table:: Metadata options :header-rows: 1 :widths: 25 15 20 40 * - 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 --------------- .. list-table:: Discovery and parsing options :header-rows: 1 :widths: 25 15 20 40 * - 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 ------------------------- .. list-table:: Numbering options :header-rows: 1 :widths: 25 15 20 40 * - 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: .. code-block:: toml [numfig_format] figure = "Fig. %s" table = "Table %s" code-block = "Listing %s" section = "Section %s" Diagnostics and strictness -------------------------- .. list-table:: Diagnostic options :header-rows: 1 :widths: 25 15 20 40 * - 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 ------------------- .. list-table:: HTML options :header-rows: 1 :widths: 25 15 20 40 * - 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 --------------------- .. list-table:: PDF options :header-rows: 1 :widths: 25 15 20 40 * - 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: .. code-block:: toml [[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 --------------------- .. list-table:: MyST Markdown options :header-rows: 1 :widths: 25 15 20 40 * - 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 ------------------- .. code-block:: toml 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 :doc:`../intersphinx` for full workflow instructions. Python autodoc options ---------------------- .. list-table:: Autodoc options :header-rows: 1 :widths: 25 15 20 40 * - 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 :doc:`../autodoc` for complete discovery rules. Odin API documentation options ------------------------------ .. list-table:: Odin domain options :header-rows: 1 :widths: 25 15 20 40 * - 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 :doc:`../odin` for complete Odin domain usage. Internationalization options ---------------------------- .. list-table:: i18n options :header-rows: 1 :widths: 25 15 20 40 * - 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 :doc:`../intl` for translation instructions.