module_map

mkdocs_terok.module_map

Module map generator — module and class docstrings grouped by layer.

Walks the source tree, extracts module-level and class-level docstrings via AST (no imports executed), and renders them as a single markdown page. When tach.toml is present, files are assigned to layers via the [[modules]] entries and ordered by the layers list. Otherwise files are grouped alphabetically by subdirectory.

FileType

Bases: Enum

Module classification heuristic for rendering style.

Source code in src/mkdocs_terok/module_map.py

class FileType(Enum):
    """Module classification heuristic for rendering style."""

    NARRATIVE = auto()
    CATALOG = auto()
    WAYPOINT = auto()

ModuleMapConfig dataclass

Configuration for the module map generator.

Source code in src/mkdocs_terok/module_map.py

@dataclass(frozen=True)
class ModuleMapConfig:
    """Configuration for the module map generator."""

    src_root: Path = field(default_factory=lambda: Path.cwd() / "src")
    tach_path: Path | None = None
    no_tach: bool = False
    title: str = "Module Map"

generate_module_map(config=None)

Generate a module map page from source docstrings.

Returns a markdown string with module and class docstrings grouped by architectural layer.

Source code in src/mkdocs_terok/module_map.py

def generate_module_map(config: ModuleMapConfig | None = None) -> str:
    """Generate a module map page from source docstrings.

    Returns a markdown string with module and class docstrings grouped
    by architectural layer.
    """
    cfg = config or ModuleMapConfig()
    pkg_root = (
        cfg.src_root
        if (cfg.src_root / "__init__.py").is_file()
        else _detect_package_root(cfg.src_root)
    )
    layers, label_root = _discover_layers(
        cfg.src_root, pkg_root, tach_path=cfg.tach_path, no_tach=cfg.no_tach
    )
    return _render(pkg_root, label_root, layers, cfg.title)

main()

Generate a module map from the command line.

Source code in src/mkdocs_terok/module_map.py

def main() -> None:
    """Generate a module map from the command line."""
    import argparse
    import sys

    parser = argparse.ArgumentParser(
        description="Generate a module map from source docstrings.",
    )
    parser.add_argument("src_root", type=Path, help="Source root directory (e.g. src/pkg)")
    parser.add_argument("--tach", type=Path, default=None, help="Path to tach.toml")
    parser.add_argument("--no-tach", action="store_true", help="Disable tach layer ordering")
    parser.add_argument("--title", default="Module Map", help="Page title")
    parser.add_argument("-o", "--output", type=Path, default=None, help="Output file (stdout)")

    args = parser.parse_args()
    config = ModuleMapConfig(
        src_root=args.src_root.resolve(),
        tach_path=args.tach.resolve() if args.tach else None,
        no_tach=args.no_tach,
        title=args.title,
    )
    result = generate_module_map(config)

    if args.output:
        args.output.write_text(result)
        print(f"Written to {args.output}", file=sys.stderr)
    else:
        print(result)