Skip to content

ledger.mkdocs.docstrings

Generate the code reference pages and navigation.

Functions:

Attributes:

  • MOD_SYMBOL –

    Modules symbol's prefix with right classes

MOD_SYMBOL module-attribute 

MOD_SYMBOL = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'

Modules symbol's prefix with right classes

generate_package_documentation 

generate_package_documentation(target: str, nav: Nav, package: str, root: Path)

Generate documentation for a given package (root-relative) into target documentation path.

Source code in ledger/mkdocs/docstrings.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
def generate_package_documentation(
    target: str,
    nav: mkdocs_gen_files.Nav,
    package: str,
    root: Path,
):
    """
    Generate documentation for a given `package` (`root`-relative) into `target` documentation path.
    """
    pkg = root / package

    src = root
    if "src" in pkg.parts:
        src /= "src"

    for path in pkg.rglob("*.py"):
        module_path = path.relative_to(src).with_suffix("")
        doc_path = module_path.with_suffix(".md")
        full_doc_path = Path(target, doc_path)

        parts = tuple(module_path.parts)
        is_init = parts[-1] == "__init__"

        if is_init:
            parts = parts[:-1]
            doc_path = doc_path.with_name("index.md")
            full_doc_path = full_doc_path.with_name("index.md")
        elif parts[-1].startswith("_"):
            continue

        nav_parts = tuple(f"{MOD_SYMBOL} {part}" for part in parts)
        nav[nav_parts] = doc_path.as_posix()

        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
            ident = ".".join(parts)
            fd.writelines(f"::: {ident}\n")

        mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path.relative_to(root))

generate_source_documentation 

generate_source_documentation(target: str, *packages: str, root: Path | None = None)

Generate source code documentation for the given root-relative packages paths into the documentation root-relative target directory.

If root is not provided, it default to the current working directory.

Source code in ledger/mkdocs/docstrings.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def generate_source_documentation(target: str, *packages: str, root: Path | None = None):
    """
    Generate source code documentation for the given root-relative `packages` paths
    into the documentation root-relative `target` directory.

    If `root` is not provided, it default to the current working directory.
    """
    nav = mkdocs_gen_files.Nav()
    root = root or Path().absolute()

    for package in packages:
        generate_package_documentation(target, nav, package, root)

    with mkdocs_gen_files.open(f"{target}/SUMMARY.md", "w") as summary:
        summary.writelines(nav.build_literate_nav())