Skip to content

ledger.mkdocs.adr

ADR/MADR management tools for Ledger projects.

This module provides tools for creating and managing Architecture Decision Records (ADRs) following the MADR 4.0 template specification.

See: - https://adr.github.io/ for ADR documentation - https://adr.github.io/madr/ for MADR template documentation

Modules:

  • cli –

    CLI commands for creating and managing ADRs/MADRs.

  • plugin –

    MkDocs plugin for ADR/MADR support.

  • utils –

    Shared utilities for ADR/MADR parsing and scanning.

Functions:

  • parse_adr –

    Parse an ADR/MADR document.

  • scan_adrs –

    Scan directory for ADR/MADR files and parse them.

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)