Skip to content

livery.extensions.docs._navblocks

livery.extensions.docs._navblocks

A package's generated tree, the nav blocks written into it, and their markers.

The generated trees, docs/_generated/ in each package and at the root, are the docs extension's: the steps of the docs phase and the site's own passes write them during a build, and they are removed before each run of the docs phase, so a tree holds only what the current build wrote. The mount merges a package's tree into its section and strips the tree's name from every link into it.

A generator emits a block's entries into the package's generated tree, and the authored docs/nav.toml places the block with a marker pair, # nav:begin <name> then # nav:end <name>; the site assembly renders the block where the markers sit. The block is data: a file docs/_generated/nav.<name>.toml holding a nav list of one-key tables, each a label to a page path inside the package's docs/. A generator in any package writes that file itself: the file is what this extension reads, and it serves no code for writing one.

Functions:

Name Description
nav_block_markers

The begin and end marker lines for a generated block in nav.toml.

nav_block_file

Where a generator emits the name block's entries: nav.<name>.toml.

write_nav_block

Emit the name block's entries into the package's generated tree; the path.

Attributes:

Name Type Description
GENERATED_DIR
GENERATED
NAV_TOML
NAV_BEGIN
NAV_END

GENERATED_DIR module-attribute

GENERATED_DIR = '_generated'

GENERATED module-attribute

GENERATED = GENERATED_DIR + '/'

NAV_TOML module-attribute

NAV_TOML = 'nav.toml'

NAV_BEGIN module-attribute

NAV_BEGIN = '# docs-nav:begin (generated; the emitter owns this block)'

NAV_END module-attribute

NAV_END = '# docs-nav:end'

nav_block_markers

nav_block_markers(name: str) -> tuple[str, str]

The begin and end marker lines for a generated block in nav.toml.

The lines between a pair belong to the generator that owns name; the surrounding tree stays hand-authored.

Source code in packages/extensions/docs/src/livery/extensions/docs/_navblocks.py
def nav_block_markers(name: str) -> tuple[str, str]:
    """The begin and end marker lines for a generated block in ``nav.toml``.

    The lines between a pair belong to the generator that owns
    *name*; the surrounding tree stays hand-authored.
    """
    return (f"# nav:begin {name}", f"# nav:end {name}")

nav_block_file

nav_block_file(generated: Path, name: str) -> Path

Where a generator emits the name block's entries: nav.<name>.toml.

Source code in packages/extensions/docs/src/livery/extensions/docs/_navblocks.py
def nav_block_file(generated: Path, name: str) -> Path:
    """Where a generator emits the *name* block's entries: `nav.<name>.toml`."""
    return generated / f"nav.{name}.toml"

write_nav_block

write_nav_block(generated: Path, name: str, entries: list[str]) -> Path

Emit the name block's entries into the package's generated tree; the path.

The file carries a nav list, the block's entries unindented. The site assembly renders it where the authored nav.toml places the block's marker pair, so nothing committed changes when the block does.

Source code in packages/extensions/docs/src/livery/extensions/docs/_navblocks.py
def write_nav_block(generated: Path, name: str, entries: list[str]) -> Path:
    """Emit the *name* block's *entries* into the package's generated tree; the path.

    The file carries a `nav` list, the block's entries unindented. The
    site assembly renders it where the authored ``nav.toml`` places the
    block's marker pair, so nothing committed changes when the block
    does.
    """
    generated.mkdir(parents=True, exist_ok=True)
    path = nav_block_file(generated, name)
    body = "\n".join(entries)
    path.write_text(
        f"# The {name!r} nav block, emitted by its generator; the authored"
        f" nav.toml places it.\nnav = [\n{body}\n]\n",
        encoding="utf-8",
    )
    return path