livery.extensions.docs._packages_page¶
livery.extensions.docs._packages_page ¶
The site's Packages section: where each package sits, in what order, and its page.
Every package sits under one entry, Packages, in a tree its contract
decides. A package whose code other packages reference by import path
sits at the shallowest of those paths, less the namespace every such
package shares: livery.toolroom.bench sits at toolroom, then
bench. A package no import path reaches sits at its folder under
packages/. A package's [docs] name, a dotted path whose last
part is its label, places it anywhere, inside another package's entry
included. Siblings come in the order the release wave publishes in,
every dependency before its dependents, and a group sorts with its
earliest member. The landing page lists the same tree, each package
with its contract's description.
Classes:
| Name | Description |
|---|---|
Node |
One place in the Packages tree: a package's, a group's, or both. |
Functions:
| Name | Description |
|---|---|
declared_place |
The place package's |
imported_place |
The shallowest import path package's code is referenced by, split at its dots. |
places |
Each package's place in the Packages tree, by its path. |
package_tree |
The Packages tree of packages; read it through |
write_packages_page |
Write the Packages landing page into the mount; its path, None without packages. |
Attributes:
| Name | Type | Description |
|---|---|---|
MOUNT |
|
|
LANDING |
|
Node
dataclass
¶
Node(label: str, package: Package | None = None, children: dict[str, Node] = dict[str, 'Node'](), rank: int = 0)
One place in the Packages tree: a package's, a group's, or both.
Attributes:
| Name | Type | Description |
|---|---|---|
label |
str
|
The place's last part, the nav's label for it. |
package |
Package | None
|
The package at this place, or None for a group. |
children |
dict[str, Node]
|
The places below it, by label. |
rank |
int
|
Where the place sorts among its siblings: its earliest package's position in the dependency order. |
Methods:
| Name | Description |
|---|---|
ordered |
The places below, dependencies first, then by label. |
declared_place ¶
The place package's [docs] name gives it, or None without one.
Raises:
| Type | Description |
|---|---|
Failed
|
when the name is not a dotted path, naming the file. |
Source code in packages/extensions/docs/src/livery/extensions/docs/_packages_page.py
imported_place ¶
The shallowest import path package's code is referenced by, split at its dots.
Read from its module roots, which the package's extensions answer. The path with the fewest parts wins; of two with as many, the one answered first. None for a package no import path reaches.
Source code in packages/extensions/docs/src/livery/extensions/docs/_packages_page.py
places ¶
Each package's place in the Packages tree, by its path.
Its [docs] name when it declares one; else its shallowest import
path (imported_place), less the first part when every such path
shares it; else its folder under packages/.
Source code in packages/extensions/docs/src/livery/extensions/docs/_packages_page.py
package_tree ¶
The Packages tree of packages; read it through Node.ordered.
Raises:
| Type | Description |
|---|---|
Failed
|
when two packages sit at one place, naming both. |
Source code in packages/extensions/docs/src/livery/extensions/docs/_packages_page.py
write_packages_page ¶
Write the Packages landing page into the mount; its path, None without packages.
Runs after the mount, so each package links to the page its section opens on. Rebuilt on every docs verb, as the mount is.