livery.extensions.docs¶
livery.extensions.docs ¶
The docs extension's names another extension reads to add to the site.
An extension that writes tables into the site's config answers the
docs.config query with a livery.extensions.docs.Writer: the
function that writes its tables, as TOML, for the config a
livery.extensions.docs.Scope describes. The docs.members query,
livery.extensions.docs.MEMBERS, answers whether the API reference
documents private members: livery.extensions.docs.PUBLIC_MEMBERS
or livery.extensions.docs.ALL_MEMBERS. The root docs/ tree's
generated directories, livery.extensions.docs.SITE_TREES, hold no
authored page. The task reference renders while the root contract turns
its step, livery.extensions.docs.TASK_REFERENCE, on: each task of a
provider a package advertises
(livery.extensions.docs.advertised_providers) publishes on the
page livery.extensions.docs.task_page names.
A generator writes its nav block as data, a nav.<name>.toml file
in the package's generated tree, and imports nothing from here for it.
Classes:
| Name | Description |
|---|---|
Scope |
What one assembled config covers, as each writer of tables is handed it. |
Functions:
| Name | Description |
|---|---|
advertised_providers |
The |
task_page |
The page the task at address publishes on, relative to the site's root. |
Attributes:
| Name | Type | Description |
|---|---|---|
ALL_MEMBERS |
|
|
MEMBERS |
Query[str]
|
|
PUBLIC_MEMBERS |
|
|
Writer |
An answer to the |
|
SITE_TREES |
|
|
TASK_REFERENCE |
|
|
__version__ |
|
Writer
module-attribute
¶
An answer to the docs.config query.
The function that writes an extension's tables for the config a
Scope describes, as TOML text, empty when the extension has nothing
to say there.
SITE_TREES
module-attribute
¶
__all__
module-attribute
¶
__all__ = ['ALL_MEMBERS', 'MEMBERS', 'PUBLIC_MEMBERS', 'SITE_TREES', 'TASK_REFERENCE', 'Scope', 'Writer', '__version__', 'advertised_providers', 'task_page']
Scope
dataclass
¶
What one assembled config covers, as each writer of tables is handed it.
Attributes:
| Name | Type | Description |
|---|---|---|
root |
Path
|
The workspace root. |
packages |
tuple[Package, ...]
|
The packages whose sections the config carries, in the site's order: every package for the site's own config, one for a package's preview. |
anchor |
str
|
The path from the config's directory to the root, with
a closing slash: empty for the site's own config at the
root, |
published |
str
|
The published site's address when the config is a preview's and the root contract names one, so a reference the preview does not carry resolves on the published site; empty for the site's own config. |
advertised_providers ¶
The footman.tasks entry-point names package advertises.
Read from the package's own committed pyproject.toml, so the
enumeration is offline and deterministic; a package without the
table provides no tasks and gets no section.
Source code in packages/extensions/docs/src/livery/extensions/docs/_taskref.py
task_page ¶
The page the task at address publishes on, relative to the site's root.
A task's page sits in the section of owner, the member that
advertises its provider, one directory per group of its address:
the workshop's coverage.leg is
packages/workshop/tasks/coverage/leg.md.
Source code in packages/extensions/docs/src/livery/extensions/docs/_taskref.py
__getattr__ ¶
Serve a public name from its module, each time it is read.
The value is never kept here, so a test that patches the name in its module is read through.