Skip to content

Docs checker

check_documentation_consistency(root='.')

Run lightweight documentation consistency checks.

Source code in src/cspilot/docs_checker.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def check_documentation_consistency(root: str | Path = ".") -> dict[str, Any]:
    """Run lightweight documentation consistency checks."""
    root_path = Path(root)
    issues: list[str] = []

    for relative in sorted(REQUIRED_DOCS):
        if not (root_path / relative).exists():
            issues.append(f"Missing documentation file: {relative}")

    cli_usage = root_path / "docs" / "cli_usage.md"
    if cli_usage.exists():
        text = cli_usage.read_text(encoding="utf-8")
        for marker in sorted(CLI_COMMAND_MARKERS):
            if marker not in text:
                issues.append(f"docs/cli_usage.md does not mention: {marker}")

    scan_paths = [
        root_path / "README.md",
        root_path / "docs",
        root_path / "mkdocs.yml",
        root_path / "_zensical.toml",
    ]
    for path in _iter_text_files(scan_paths):
        text = path.read_text(encoding="utf-8", errors="replace")
        for marker in FORBIDDEN_TEMPLATE_MARKERS:
            if marker in text:
                issues.append(f"Template marker '{marker}' remains in {path.relative_to(root_path)}")

    return {
        "success": not issues,
        "checked_root": str(root_path),
        "issues": issues,
        "required_docs": sorted(REQUIRED_DOCS),
        "cli_markers": sorted(CLI_COMMAND_MARKERS),
    }