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_block_file |
Where a generator emits the name block's entries: |
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 |
|
NAV_BEGIN
module-attribute
¶
nav_block_markers ¶
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
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.
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.