cli.build.docs.readme package

Submodules

cli.build.docs.readme.cosmos module

Derive a Cosmos mermaid flowchart from every role’s meta/services.yml.

The role box lists EVERY service the role declares. Around it:

Dependencies roles this role consumes, on the left. A consumption is a

service whose enabled/shared flag names another role ('<role>' in group_names), whose key matches another role’s provides (provision) name, or whose key is another role’s own primary service key while both flags are on.

Dependents roles that consume THIS role, on the right. The mirror of the

above: another role names this one, or declares a service keyed by this role’s provides name (e.g. web-app-keycloak provides: sso and every role with an sso service).

provides matching runs in both directions, so a provider (e.g. openldap provides: ldap) is picked up even when the consuming flag uses a groups[...] form the group_names regex cannot read.

Primary-key matching covers the mandatory relationship, where the consumer pins the provider on unconditionally (enabled: true, shared: true) and no group_names reference is left to read — web-svc-asset consuming web-svc-file’s file is the canonical case.

Edge style encodes the flag: a solid edge is a fixed (literal true) relationship, a dashed edge is variable (a {{ ... }} conditional), and a red 0..0 edge is one the role turns off (enabled and shared both literally false) — the relationship exists in the metadata but carries nothing at deploy time.

run_after is deliberately NOT read: it is a deploy-ordering hint, not a runtime dependency. The wider cosmos (federation peers, external bridged networks) cannot be derived from metadata and is left for the author to add.

cli.build.docs.readme.cosmos.derive_cosmos_mermaid(role_dir: Path, role_name: str) → str

Return a mermaid flowchart source (no ``` fences) for the role.

cli.build.docs.readme.generate module

Generate / complete a role README from the template.

The generator owns only the sections it can derive from metadata:

• Cosmos – the mermaid diagram, from meta/services.yml.

• Quick Setup – the deploy commands, from the role id (invokable roles

  only; removed from non-invokable roles).

• Credits – the fixed block, from meta/main.yml author.

Prose sections (Description, Overview, Features, Use Cases) cannot be synthesised, so an existing README’s prose is never rewritten. On a brand new README the prose is emitted as fill-in placeholders.

Modes:

• default – add a managed section only when it is missing.

• override – regenerate every managed section, overwriting the current

  content in place (position is left untouched).

• only – restrict the run to a subset of the managed sections

  (e.g. ("Cosmos",) for --update-cosmos).

cli.build.docs.readme.generate.generate_readme(role_dir, role_name: str, *, override: bool = False, only: tuple[str, ...] = ('Cosmos', 'Quick Setup', 'Credits')) → tuple[str | None, list[str]]

Return (new_text_or_None, actions).

new_text_or_None is None when nothing changed.

cli.build.docs.readme.generate.role_dirs(roles_root=None) → list

cli.build.docs.readme.overview module

Generate the invokable-role overview table in the repository README.

Usage:

python -m cli.build.docs.readme.overview [–check] [–readme PATH] [–roles-dir DIR]

The table lives in its own ## Roles Overview 🧩 section directly above ## Use it online 🚀 in the root README.md and is fully regenerated on every run; every other section stays untouched. Rows are the invokable roles, sorted ascending by the Entity column.

Rows are the invokable roles inside the tested lifecycle envelope, sorted ascending by name.

Columns:

Name Role README H1 title, linked to the role directory. Status Role lifecycle stage. Description galaxy_info.description from meta/main.yml. More Emoji links: 🌐 homepage, 🎬 video (both from

meta/info.yml, omitted when absent) and 🛠️ the role README’s Quick Setup section.

Integrated with README titles of the role’s direct service integrations

(complexity graph, level 1), linked to the roles.

cli.build.docs.readme.overview.build_table(roles_dir: Path) → str

cli.build.docs.readme.overview.main(argv: list[str] | None = None) → int

cli.build.docs.readme.overview.replace_section(readme_text: str, table: str) → str

cli.build.docs.readme.schema module

Derive the role-README section schema from the Jinja template.

templates/roles/README.md.j2.tmpl is the single source of truth. The required sections are the H2s the template emits with no optional context; the optional sections are the extra H2s that appear once every {% if ... %}-guarded variable is supplied. Rendering the template both ways and diffing the H2 sets keeps the lint and the generator in lock-step with the template.

cli.build.docs.readme.schema.canonical_order() → tuple[str, ...]

Full H2 order (required + optional) as the template lays them out.

cli.build.docs.readme.schema.credits_heading() → str

The last required section (Credits by convention).

cli.build.docs.readme.schema.optional_sections() → tuple[str, ...]

cli.build.docs.readme.schema.render_full() → str

cli.build.docs.readme.schema.render_required() → str

cli.build.docs.readme.schema.required_sections() → tuple[str, ...]

H2 titles the template emits without any optional context (mandatory).

cli.build.docs.readme.sections module

Split a Markdown README into its H2 sections (fence-aware).

class cli.build.docs.readme.sections.Readme(preamble: str, sections: list[tuple[str, str]])

Bases: object

A parsed README: everything before the first H2, then its H2 blocks.

preamble: str

render() → str

sections: list[tuple[str, str]]

titles() → list[str]

cli.build.docs.readme.sections.h2_titles(text: str) → list[str]

Return the ordered H2 titles of a Markdown document (fence-aware).

cli.build.docs.readme.sections.parse_readme(text: str) → Readme

Module contents

Role README schema, section parsing, Cosmos derivation, and generation.

templates/roles/README.md.j2.tmpl is the single source of truth for the role-README structure. cli.build.docs.readme.schema derives the required/optional section set from it; the lint (tests/lint/ansible/roles/test_readme.py) and the generator (python -m cli.build.docs.readme) both consume that same schema so the three never drift.