Skip to content

ledger.mkdocs.adr.utils

Shared utilities for ADR/MADR parsing and scanning.

This module provides common functionality used by both the CLI and MkDocs plugin to parse and scan Architecture Decision Records (ADRs) following the MADR format.

Functions:

  • is_adr –

    Check if filename matches ADR naming convention.

  • parse_adr –

    Parse an ADR/MADR document.

  • scan_adrs –

    Scan directory for ADR/MADR files and parse them.

is_adr 

is_adr(filename: str) -> bool

Check if filename matches ADR naming convention.

Parameters:

  • filename

    (str) –

    Candidate filename (e.g. "0001-use-postgresql.md").

Returns: True if it matches NNNN-*.md pattern.

Source code in ledger/mkdocs/adr/utils.py 
19
20
21
22
23
24
25
26
27
28
def is_adr(filename: str) -> bool:
    """
    Check if filename matches ADR naming convention.

    Args:
        filename: Candidate filename (e.g. "0001-use-postgresql.md").

    Returns: True if it matches NNNN-*.md pattern.
    """
    return bool(re.match(r"\d{4}-.*\.md$", filename))

parse_adr 

parse_adr(file_path: Path, base_path: Path | None = None) -> ADRDocument

Parse an ADR/MADR document.

Parameters:

  • file_path

    (Path) –

    Path to ADR file.

  • base_path

    (Path | None, default: None ) –

    Base path for resolving relatives; defaults to file parent.

Returns: Parsed ADR document.

Raises:

Source code in ledger/mkdocs/adr/utils.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def parse_adr(file_path: Path, base_path: Path | None = None) -> ADRDocument:
    """
    Parse an ADR/MADR document.

    Args:
        file_path: Path to ADR file.
        base_path: Base path for resolving relatives; defaults to file parent.

    Returns: Parsed ADR document.

    Raises:
        Exception: On parse failure.
    """
    if base_path is None:
        base_path = file_path.parent
    parser = get_parser("MADR4")
    return parser.parse(file_path, base_path)

scan_adrs 

scan_adrs(directory: Path, base_path: Path | None = None) -> list[ADRDocument]

Scan directory for ADR/MADR files and parse them.

Parameters:

  • directory

    (Path) –

    Directory containing ADR files.

  • base_path

    (Path | None, default: None ) –

    Base path for relative resolution; defaults to directory parent.

Returns: Parsed documents sorted by document_id.

Note

Emits warnings when a file fails to parse.

Source code in ledger/mkdocs/adr/utils.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def scan_adrs(directory: Path, base_path: Path | None = None) -> list[ADRDocument]:
    """
    Scan directory for ADR/MADR files and parse them.

    Args:
        directory: Directory containing ADR files.
        base_path: Base path for relative resolution; defaults to directory parent.

    Returns: Parsed documents sorted by document_id.

    Note:
        Emits warnings when a file fails to parse.
    """
    adrs: list[ADRDocument] = []
    if not directory.exists():
        return adrs

    effective_base = base_path or directory.parent
    for file_path in sorted(directory.glob("*.md")):
        if is_adr(file_path.name):
            try:
                doc = parse_adr(file_path, effective_base)
                adrs.append(doc)
            except Exception as exc:
                warnings.warn(f"Failed to parse ADR {file_path}: {exc}", stacklevel=2)
                continue

    return sorted(adrs, key=lambda x: x.document_id or 0)