Skip to content

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 footman.tasks entry-point names package advertises.

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 docs.config query.

SITE_TREES
TASK_REFERENCE
__version__

TYPE_CHECKING module-attribute

TYPE_CHECKING = False

ALL_MEMBERS module-attribute

ALL_MEMBERS = 'all'

MEMBERS module-attribute

MEMBERS: Query[str] = Query('docs.members')

PUBLIC_MEMBERS module-attribute

PUBLIC_MEMBERS = 'public'

Writer module-attribute

Writer = Callable[[Scope], str]

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

SITE_TREES = ('packages', 'releases', 'tasks', 'tools', 'development')

TASK_REFERENCE module-attribute

TASK_REFERENCE = 'docs.task-reference'

__version__ module-attribute

__version__ = '0.0.0'

__all__ module-attribute

__all__ = ['ALL_MEMBERS', 'MEMBERS', 'PUBLIC_MEMBERS', 'SITE_TREES', 'TASK_REFERENCE', 'Scope', 'Writer', '__version__', 'advertised_providers', 'task_page']

Scope dataclass

Scope(root: Path, packages: tuple[Package, ...], anchor: str = '', published: str = '')

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, ../../ for a preview two levels below it. A path relative to the root reaches the same file from the config with this before it.

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.

root instance-attribute

root: Path

packages instance-attribute

packages: tuple[Package, ...]

anchor class-attribute instance-attribute

anchor: str = ''

published class-attribute instance-attribute

published: str = ''

advertised_providers

advertised_providers(package: Package) -> list[str]

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
def advertised_providers(package: Package) -> list[str]:
    """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.
    """
    pyproject = package.directory / "pyproject.toml"
    if not pyproject.is_file():
        return []
    parsed = tomllib.loads(pyproject.read_text("utf-8"))
    project = parsed.get("project")
    points = project.get("entry-points") if isinstance(project, dict) else None
    table = points.get("footman.tasks") if isinstance(points, dict) else None
    if not isinstance(table, dict):
        return []
    return sorted(str(name) for name in table)

task_page

task_page(owner: str, address: str) -> str

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
def task_page(owner: str, address: str) -> str:
    """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``.
    """
    return f"packages/{owner}/{PAGES}/{'/'.join(address.split('.'))}.md"

__getattr__

__getattr__(name: str) -> object

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.

Source code in packages/extensions/docs/src/livery/extensions/docs/__init__.py
def __getattr__(name: str) -> object:
    """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.
    """
    import importlib

    module = _EXPORTS.get(name)
    if module is None:
        raise AttributeError(
            f"module 'livery.extensions.docs' has no attribute {name!r}"
        )
    return getattr(importlib.import_module(module), name)