livery.extensions.docs._contract¶
livery.extensions.docs._contract ¶
What the docs extension reads from a workspace's contracts.
The root contract's [docs] table, which the extension owns; the
generators a package declares under [docs] generators, with the
system packages each needs on a docs machine; and the seam the site
publishes through. The extension's declaration file names
docs_requirements as both jobs' installs and publish_seam as
the deploy's deploy, so the CI render asks them and reads no
[docs] table itself. The site's assembly reads the same two.
Classes:
| Name | Description |
|---|---|
Generator |
One generator a package lists under |
Functions:
| Name | Description |
|---|---|
docs_table |
The root contract's |
project_name |
The workspace's stable name for the site. |
package_generators |
The docs generators package declares, in its contract's order. |
generator_outputs |
The paths the generators every package lists write, each once, in order. |
docs_requirements |
The union of every declared generator's system requirements, sorted. |
publish_seam |
The seam the site publishes through: pages, container, ssh, or none. |
Attributes:
| Name | Type | Description |
|---|---|---|
SEAMS |
|
|
DEFAULT_SEAMS |
|
DEFAULT_SEAMS
module-attribute
¶
Generator ¶
Bases: NamedTuple
One generator a package lists under [docs] generators.
Attributes:
| Name | Type | Description |
|---|---|---|
verb |
str
|
The verb, a footman task the package ships. |
requires |
tuple[str, ...]
|
The system packages the verb needs on a docs machine. |
outputs |
tuple[str, ...]
|
The paths the verb writes outside the generated
trees, each relative to the root, a directory ending in
|
docs_table ¶
The root contract's [docs] table; empty when undeclared.
Source code in packages/extensions/docs/src/livery/extensions/docs/_contract.py
project_name ¶
The workspace's stable name for the site.
The root project's name, never the directory's: a worktree's directory name would make the same contract render differently per checkout and turn the drift gate against itself.
Source code in packages/extensions/docs/src/livery/extensions/docs/_contract.py
package_generators ¶
The docs generators package declares, in its contract's order.
A package's workshop.toml [docs] table lists them under
generators: a verb name (a footman task the package ships), or
a table naming the verb, the system tools the generator needs on a
docs machine and the paths it writes outside the generated trees
({ verb = "...", requires = [...], outputs = [...] }). Anything
else refuses naming the file and the entry. Empty without a
declaration.
Source code in packages/extensions/docs/src/livery/extensions/docs/_contract.py
generator_outputs ¶
The paths the generators every package lists write, each once, in order.
What a generator declares under outputs, which the docs phase's
run removes once no listed generator declares it any more.
Source code in packages/extensions/docs/src/livery/extensions/docs/_contract.py
docs_requirements ¶
The union of every declared generator's system requirements, sorted.
What the site's CI jobs install before they build. Empty for a
workspace without a packages directory.
Source code in packages/extensions/docs/src/livery/extensions/docs/_contract.py
publish_seam ¶
The seam the site publishes through: pages, container, ssh, or none.
The root contract's [docs] publish wins, one of SEAMS, which
the contract's judge holds it to; without it the forge kind picks
its default from DEFAULT_SEAMS.