src/documate/config.py
Module

config.py

config.py — everything project-specific about the repo documate is pointed at.

src/documate/config.py5 documented symbols

Overview

config.py — everything project-specific about the repo documate is pointed at.

documate's logic is repo-agnostic; this is where a given repo's specifics live, behind neutral defaults plus an optional JSON override. A repo with the default layout (docs under docs/, graph at .documate/graph.db) needs no config. Anything else drops a documate.config.json and overrides only the keys it cares about. Search order:

    $DOCUMATE_CONFIG (absolute path)   ->  explicit, wins
    <root>/documate.config.json        ->  the conventional home
    <root>/.documate.config.json       ->  repo-root dotfile alternative

Keys (all optional; omitted keeps the default):

    docs_dir       where the docs live: generated pages are written here, authored
                   pages are scanned for anchors here                 ("docs")
    site_dir       where `docs --html` writes the static site (a build
                   artifact — gitignore it)                            ("site")
    graph_db       where the indexer writes its graph             (".documate/graph.db")
    skip_dirs      path substrings never treated as source-of-truth: not indexed,
                   no pages, no briefs (vendored/generated/build trees)
    test_markers   path substrings marking test code — directories ("/tests/") or
                   filename suffixes ("_test.go")  (prefer prod over these)

The two list keys EXTEND their defaults rather than replace them — adding your one vendored tree must not cost you the stock list. Prefix an entry with ! to drop a default ("!/vendor/" un-skips vendor/). default_base git ref check compares against ("main") project_name the name the generated pages carry (default: derived from the checkout, worktree-safe via the git common dir) format_cmd command --ai runs over the source files it touched, paths appended ("clang-format -i"); None skips formatting doc_width column limit --ai wraps drafted doc comments to (100); the comment markers and indentation count toward it

Unknown config keys are a hard error — a typo silently doing nothing is the exact rot documate exists to stop. Stdlib only.

used by src/documate/cli.py, src/documate/core.py

API

Cclass Config

src/documate/config.py:97

Resolved config. Paths absolute.

called by load_config

F_config_path(root: Path) -> Path | None

src/documate/config.py:112

The config file to honour: $DOCUMATE_CONFIG, else the first repo-root name that exists.

called by load_config, scaffold

Fscaffold(root: Path) -> Path | None

src/documate/config.py:125

Write a starter documate.config.json at the repo root for the user to edit, and return its path — or None when a config already exists (never clobbered). The layout keys carry their real defaults so the file names every knob; the two list keys start empty because they EXTEND the built-in lists (an empty list adds nothing — it's the honest "no overrides yet").

calls _config_path

F_width(value, src: Path | None) -> int

src/documate/config.py:145

doc_width as a usable column limit. A width narrower than the comment markers themselves can't wrap anything, so a nonsense value is a hard error like an unknown key — not a silent fallback that quietly stops wrapping.

called by load_config

Fload_config(root: Path) -> Config

src/documate/config.py:154

Merge the override file (if any) over the defaults and resolve to a Config.

calls Config, _config_path, _width