Skip to content

livery.extensions.mkdocstrings._pages

livery.extensions.mkdocstrings._pages

The python API reference: a page per module, and the nav block that lists them.

The mkdocstrings step of the docs phase runs once per package whose set holds python and writes the package's reference into its generated tree: a page per module of each of its roots under api/, each a single ::: directive that the python handler renders with the module's members, and the api nav block that lists the pages, nav.api.toml, which the site places in the package's section. Both are rebuilt whole, so a module that went takes its page with it, and a package that declines its reference with [docs] api = false keeps neither.

The handler reads a package's modules from its sources and from the directories the step's paths option names, and its options and inventories are the ones the site's config writes (the docs.config answer in this extension's _config module).

The pages and the block are data the docs extension reads: the generated tree is docs/_generated/ in the package, and the block is the file nav.api.toml in it, a nav list of one-key tables, each a label to a page path inside the package's docs/. This extension writes both itself.

Functions:

Name Description
documented

Whether the reference documents package, by the extensions its set holds.

declines_api

Whether package turns its reference off with [docs] api = false.

roots

The importable roots under src: each topmost directory with an __init__.py.

pages

(page path, dotted import path) per module of each root, public first.

declared_paths

The directories package's paths option names, relative to the package.

sources

The handler's search paths for package, relative to the workspace root.

write_reference

Write package's API pages and its nav block; the pages written.

pages_run

Write the API reference of the package the run names: the docs phase's step.

Attributes:

Name Type Description
STEP
GENERATED_DIR
API_DIR
NAV_BLOCK
INVENTORIES
OPTIONS dict[str, object]

STEP module-attribute

STEP = 'docs.mkdocstrings'

GENERATED_DIR module-attribute

GENERATED_DIR = '_generated'

API_DIR module-attribute

API_DIR = 'api'

NAV_BLOCK module-attribute

NAV_BLOCK = 'api'

INVENTORIES module-attribute

INVENTORIES = ('https://docs.python.org/3/objects.inv',)

OPTIONS module-attribute

OPTIONS: dict[str, object] = {'docstring_style': 'google', 'show_if_no_docstring': True, 'show_root_heading': True, 'show_root_full_path': True, 'separate_signature': True, 'show_signature_annotations': True, 'signature_crossrefs': True, 'members_order': 'source', 'merge_init_into_class': True, 'summary': True, 'heading_level': 2}

documented

documented(package: Package) -> bool

Whether the reference documents package, by the extensions its set holds.

A package whose set holds an extension the step names, python, is documented; any other is never asked. The step is read from the installed declaration in a process that mounted nothing, as the site's config may be.

Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
def documented(package: Package) -> bool:
    """Whether the reference documents *package*, by the extensions its set holds.

    A package whose set holds an extension the step names, python, is
    documented; any other is never asked. The step is read from the
    installed declaration in a process that mounted nothing, as the
    site's config may be.
    """
    return bool(set(step_extensions(STEP)) & set(extension_set(package)))

declines_api

declines_api(package: Package) -> bool

Whether package turns its reference off with [docs] api = false.

The key is the docs extension's, read here from the package's contract as data.

Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
def declines_api(package: Package) -> bool:
    """Whether *package* turns its reference off with ``[docs] api = false``.

    The key is the docs extension's, read here from the package's
    contract as data.
    """
    table = read_contract(package.directory).get("docs") or {}
    return isinstance(table, dict) and table.get("api") is False

roots

roots(src: Path) -> list[Path]

The importable roots under src: each topmost directory with an __init__.py.

Shallowest first, then by path. A directory with no __init__.py is a namespace and marks nothing, so a package under one is a root of its own, and a package under a root is part of that root.

Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
def roots(src: Path) -> list[Path]:
    """The importable roots under *src*: each topmost directory with an ``__init__.py``.

    Shallowest first, then by path. A directory with no ``__init__.py``
    is a namespace and marks nothing, so a package under one is a root
    of its own, and a package under a root is part of that root.
    """
    found: list[Path] = []
    marks = sorted(src.rglob("__init__.py"), key=lambda path: (len(path.parts), path))
    for mark in marks:
        if not any(mark.parent.is_relative_to(root) for root in found):
            found.append(mark.parent)
    return found

pages

pages(package: Package) -> list[tuple[str, str]]

(page path, dotted import path) per module of each root, public first.

Every module gets a page, underscore-private included: a docstring is published the moment it is written. Public sorts before private at every level of the tree, and a package's __init__ is its index page. A package that ships more than one root, as a wheel shipping two does, documents each: the shallowest root's pages sit at the reference's top, and each further root's under a directory named by its dotted path, after them. A package may decline the whole reference with [docs] api = false, the shape a forwarding shim takes: its surface is another package's, and documenting the forwarders would document the real thing twice.

Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
def pages(package: Package) -> list[tuple[str, str]]:
    """(page path, dotted import path) per module of each root, public first.

    Every module gets a page, underscore-private included: a docstring
    is published the moment it is written. Public sorts before private
    at every level of the tree, and a package's ``__init__`` is its
    index page. A package that ships more than one root, as a wheel
    shipping two does, documents each: the shallowest root's pages sit
    at the reference's top, and each further root's under a directory
    named by its dotted path, after them. A package may decline the
    whole reference with ``[docs] api = false``, the shape a forwarding
    shim takes: its surface is another package's, and documenting the
    forwarders would document the real thing twice.
    """
    if declines_api(package):
        return []
    src = package.directory / "src"
    if not src.is_dir():
        return []
    marked = roots(src)
    if not marked:
        # A root with no __init__.py: the first module the package owns.
        owned = _owned_root(package, src)
        marked = [] if owned is None else [owned]
    found: list[tuple[str, str]] = []
    for index, root in enumerate(marked):
        prefix = "" if index == 0 else ".".join(root.relative_to(src).parts) + "/"
        found += [(prefix + page, dotted) for page, dotted in _root_pages(src, root)]
    return found

declared_paths

declared_paths(package: Package) -> list[str]

The directories package's paths option names, relative to the package.

Directories holding modules the pages reference beyond the package's sources: rendered stubs, for one. A value that is not a list of strings refuses naming the contract.

Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
def declared_paths(package: Package) -> list[str]:
    """The directories *package*'s ``paths`` option names, relative to the package.

    Directories holding modules the pages reference beyond the
    package's sources: rendered stubs, for one. A value that is not a
    list of strings refuses naming the contract.
    """
    return list(cast("list[str]", step_option(STEP, package, "paths")))

sources

sources(package: Package) -> list[str]

The handler's search paths for package, relative to the workspace root.

Its sources while it has pages, then the directories its paths option names.

Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
def sources(package: Package) -> list[str]:
    """The handler's search paths for *package*, relative to the workspace root.

    Its sources while it has pages, then the directories its ``paths``
    option names.
    """
    name = package.member
    found = [f"packages/{name}/src"] if pages(package) else []
    found += [f"packages/{name}/{extra}" for extra in declared_paths(package)]
    return found

write_reference

write_reference(package: Package) -> list[str]

Write package's API pages and its nav block; the pages written.

One page per module, each a single directive, under api/ in the generated tree the site's mount merges, so the pages publish under the package's own path, and the block listing them beside them. Both are rebuilt whole: a package with no page now keeps neither.

Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
def write_reference(package: Package) -> list[str]:
    """Write *package*'s API pages and its nav block; the pages written.

    One page per module, each a single directive, under ``api/`` in
    the generated tree the site's mount merges, so the pages publish
    under the package's own path, and the block listing them beside
    them. Both are rebuilt whole: a package with no page now keeps
    neither.
    """
    generated = package.directory / "docs" / GENERATED_DIR
    base = generated / API_DIR
    block = generated / f"nav.{NAV_BLOCK}.toml"
    shutil.rmtree(base, ignore_errors=True)
    modules = pages(package)
    if not modules:
        block.unlink(missing_ok=True)
        return []
    for page, dotted in modules:
        target = base / page
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(f"# `{dotted}`\n\n::: {dotted}\n", encoding="utf-8")
    entries = ['{ "API" = [']
    entries += [
        f'    {{ "{dotted}" = "{GENERATED_DIR}/{API_DIR}/{page}" }},'
        for page, dotted in modules
    ]
    entries.append("] },")
    body = "\n".join(entries)
    block.write_text(
        f"# The {NAV_BLOCK!r} nav block, emitted by its generator; the authored"
        f" nav.toml places it.\nnav = [\n{body}\n]\n",
        encoding="utf-8",
    )
    return [page for page, _dotted in modules]

pages_run

pages_run(ctx: PhaseContext) -> None

Write the API reference of the package the run names: the docs phase's step.

The pages and the nav block of write_reference, the count said.

Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
def pages_run(ctx: PhaseContext) -> None:
    """Write the API reference of the package the run names: the docs phase's step.

    The pages and the nav block of `write_reference`, the count said.
    """
    package = ctx.member
    written = write_reference(package)
    if written:
        print(f"  API pages for {package.member}: {len(written)}")