Skip to content

livery.extensions.docs._steps

livery.extensions.docs._steps

The docs extension's steps: generators run, and links resolve.

docs.generators, a step of the docs phase, runs the verbs each package names under [docs] generators before the site builds. lint.doclinks reads the authored markdown of the workspace's docs/ and of every member's docs/, and refuses a link to a file that does not exist or an anchor no heading of the target makes.

The strict site build judges what they leave out: the links into the pages generated at build time, the pages a package's own generators write, and the nav.

Functions:

Name Description
link_problems

Every unresolvable link or anchor in the authored docs under root.

headings_removed

Whether a changed markdown file lost a heading, an anchor a link may name.

run_generators

Run every package's declared docs generators; the verbs run.

generators_run

Run the verbs the packages name under [docs] generators: a docs step.

doclinks_run

Attributes:

Name Type Description
SITE_TREES

SITE_TREES module-attribute

SITE_TREES = ('packages', 'releases', 'tasks', 'tools', '_extensions')
link_problems(root: Path, pages: frozenset[str] | None = None) -> list[str]

Every unresolvable link or anchor in the authored docs under root.

A link into packages/<name>/, where the site mounts each member's docs, maps back to that package's docs/; a generated target and a package's changelog page are written at build time, and the strict build judges them. pages keeps the judgment to those root-relative pages; every link still resolves against the whole tree.

Source code in packages/extensions/docs/src/livery/extensions/docs/_steps.py
def link_problems(root: Path, pages: frozenset[str] | None = None) -> list[str]:
    """Every unresolvable link or anchor in the authored docs under *root*.

    A link into `packages/<name>/`, where the site mounts each member's
    docs, maps back to that package's `docs/`; a generated target and a
    package's changelog page are written at build time, and the strict
    build judges them. *pages* keeps the judgment to those
    root-relative pages; every link still resolves against the whole
    tree.
    """
    problems: list[str] = []
    packages = discover_packages(root)
    for page in _pages(root, packages):
        if pages is not None and page.relative_to(root).as_posix() not in pages:
            continue
        text = page.read_text("utf-8")
        for target in _LINK_RE.findall(text):
            if target.startswith(("http://", "https://", "mailto:")):
                continue
            path_part, _, anchor = target.partition("#")
            if not path_part:
                resolved = page
            else:
                resolved = (page.parent / path_part).resolve()
                if path_part == "changelog.md" and "packages" in page.parts:
                    continue
                depth = _member_depth(packages, Path(path_part))
                if depth:
                    parts = Path(path_part).parts
                    resolved = (
                        root.joinpath(*parts[:depth]) / "docs" / Path(*parts[depth:])
                    ).resolve()
                elif GENERATED_DIR in path_part:
                    continue
            if not resolved.is_file():
                problems.append(
                    f"{page.relative_to(root).as_posix()}: {target} does not exist"
                )
                continue
            if anchor and resolved.suffix == ".md":
                slugs = {
                    _slug(heading)
                    for heading in _HEADING_RE.findall(resolved.read_text("utf-8"))
                }
                if anchor not in slugs:
                    problems.append(
                        f"{page.relative_to(root).as_posix()}: {target} anchors nothing"
                    )
    return problems

headings_removed

headings_removed(changes: Changes) -> bool

Whether a changed markdown file lost a heading, an anchor a link may name.

A link in an unchanged page may point at it, so lint.doclinks then judges every page.

Source code in packages/extensions/docs/src/livery/extensions/docs/_steps.py
def headings_removed(changes: Changes) -> bool:
    """Whether a changed markdown file lost a heading, an anchor a link may name.

    A link in an unchanged page may point at it, so ``lint.doclinks``
    then judges every page.
    """
    for path in changes.paths:
        if not path.endswith(".md"):
            continue
        before = changes.text_before(path)
        if not before:
            continue
        now = changes.root / path
        after = now.read_text("utf-8") if now.is_file() else ""
        had = {_slug(heading) for heading in _HEADING_RE.findall(before)}
        has = {_slug(heading) for heading in _HEADING_RE.findall(after)}
        if had - has:
            return True
    return False

run_generators

run_generators(root: Path) -> list[str]

Run every package's declared docs generators; the verbs run.

Each verb runs as its own runner invocation at the workspace root, in the packages' order and each verb once, so a generator is the task a person would type. A failing generator turns the build red with the verb and its package named; its own output has already streamed. Generators must be idempotent: a second run on unchanged input is a no-op.

Source code in packages/extensions/docs/src/livery/extensions/docs/_steps.py
def run_generators(root: Path) -> list[str]:
    """Run every package's declared docs generators; the verbs run.

    Each verb runs as its own runner invocation at the workspace
    root, in the packages' order and each verb once, so a generator is
    the task a person would type. A failing generator turns the build
    red with the verb and its package named; its own output has already
    streamed. Generators must be idempotent: a second run on unchanged
    input is a no-op.
    """
    import shutil

    import livery.footman as footman
    from livery.extensions.docs._contract import package_generators
    from livery.workshop import discover_packages

    ran: list[str] = []
    runner = ""
    for package in discover_packages(root):
        for generator in package_generators(package):
            verb = generator.verb
            if verb in ran:
                continue  # two declarations of one shared verb run it once
            if not runner:
                runner = shutil.which(footman.prog()) or ""
                if not runner:
                    fail(
                        f"{footman.prog()} is not on PATH, so the declared"
                        f" docs generators cannot run; enter the"
                        " environment (source setup.sh) first"
                    )
            code = footman.run([runner, verb], cwd=root, nofail=True)
            if int(code) != 0:
                fail(
                    f"docs generator `{footman.prog()} {verb}`"
                    f" ({package.name}) exited {int(code)}"
                )
            ran.append(verb)
    return ran

generators_run

generators_run(ctx: PhaseContext) -> None

Run the verbs the packages name under [docs] generators: a docs step.

run_generators over the workspace, the verbs it ran said.

Source code in packages/extensions/docs/src/livery/extensions/docs/_steps.py
def generators_run(ctx: PhaseContext) -> None:
    """Run the verbs the packages name under ``[docs] generators``: a docs step.

    `run_generators` over the workspace, the verbs it ran said.
    """
    ran = run_generators(ctx.root)
    if ran:
        print(f"  generators: {', '.join(ran)}")
doclinks_run(ctx: PhaseContext) -> None
Source code in packages/extensions/docs/src/livery/extensions/docs/_steps.py
def doclinks_run(ctx: PhaseContext) -> None:
    problems = link_problems(ctx.root, selected_files(ctx))
    if problems:
        fail("links that resolve nothing:\n  " + "\n  ".join(problems))