0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-06 10:59:59 +00:00

Files

T

kevinveenbirkenbachandClaude Opus 4.8 90b3845998 feat(readme): role README generator with Cosmos diagrams, Quick Setup, and lint

Add cli/build/readme: derives each role README's managed sections from
templates/roles/README.md.j2.tmpl (the Cosmos mermaid diagram from
meta/services.yml, an invokable-gated Quick Setup, and Credits).

The Cosmos diagram shows dependencies, every declared service, and
dependents (roles that consume this one, matched by role name and by
provides provision-name in both directions). Role nodes carry deploy-mode
emoji markers (compose/swarm/host); disabled and shared services get a
stop mark; dependents are capped at 12.

test_readme enforces the Quick Setup body is byte-exact with the template
render. `make readme-generate` and `make cosmos` regenerate; `make cosmos`
also runs inside `make quality`.

Refactor: utils/symbol_glossary.py is the single source of truth for the
word/emoji mapping (unique project-wide), consumed by the complexity
matrix and the Cosmos builder. utils/roles/deploy.py holds role_has_stack
and role_deploy_modes, shared by both so the logic never drifts.

Add `make lint-mermaid` and its CI workflow, rendering every diagram via
mermaid-cli; the render step provisions chrome-headless-shell and unzip
on demand so it works in the minimal container.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-17 14:44:33 +02:00

4.5 KiB

Raw Permalink Blame History

Role README 📄

Every Ansible role MUST contain a README.md at the role root. This page defines the required structure and content rules. For general documentation rules (links, writing, emojis, RFC 2119 keywords), see documentation.md.

Structure 📋

Role README files MUST follow this section order. Optional sections MAY be omitted when they add no value for the role.

1. Title (required) 🏷️

The H1 heading MUST be the human-readable name of the application or service, not the role ID.

# Nextcloud

2. Description (required) 📖

A short paragraph that describes what the software is. You MUST NOT describe what the role does here. Link the software name to its official website on first use.

## Description

[Nextcloud](https://nextcloud.com/) is a self-hosted file sync and share platform …

3. Overview (required) 🗺️

A short paragraph that describes what the role does: what it deploys, configures, and integrates. Reference any companion documentation files (e.g. Administration.md) here using file-name link text.

## Overview

This role deploys Nextcloud using Docker Compose …
For administration details see [Administration.md](./Administration.md).

4. Cosmos (required) 🌌

A ## Cosmos section MUST contain a single Mermaid flowchart that places the role in the Infinito.Nexus cosmos. Group the nodes with subgraphs into three families:

Capabilities — the containers/components this role deploys (from meta/services.yml).
Dependencies — the central services and sibling roles it consumes (the enabled: "{{ '<role>' in group_names }}" service flags, plus run_after and any meta/main.yml dependencies).
Cosmos — the outward reach: federation peers, external networks bridged in, upstream projects.

Draw only what the role metadata declares; do not invent services. Mermaid node ids MUST NOT be reserved words (call, end, click, class, graph, style, subgraph).

## Cosmos

```mermaid
flowchart LR
    subgraph deps [Dependencies]
        postgres["svc-db-postgres"]
    end
    subgraph role [web-app-example]
        app["App container"]
    end
    postgres --> app
```

5. Features (required) ✨

A bulleted list of the most important capabilities. Each item MUST start with a bold label followed by a colon and a short explanation.

## Features

- **Self-hosted:** Run the application under your own domain …
- **LDAP Integration:** Authenticate users via a central directory …

6. Use Cases (optional) 🎯

Use this section for the concrete scenarios the role is a good fit for, when they are not obvious from Description and Overview. Omit it for roles where the use cases are self-evident.

7. Developer Notes (optional) 🔧

Link to role-local documentation files such as Administration.md, Installation.md, or Development.md. You MUST use file-name link text. Never use the full path.

## Developer Notes

See [Administration.md](./Administration.md) for live container inspection and LDAP configuration.

8. Further Resources (optional) 🔗

A list of external links relevant to the software or the deployment. Link text MUST be a descriptive label or the domain name. Never use the full URL.

## Further Resources

- [Nextcloud Official Website](https://nextcloud.com/)
- [Nextcloud Admin Manual](https://docs.nextcloud.com/…)

9. Credits (required) 🙏

Always the last section. MUST follow this fixed format:

## Credits

Implemented by **[Author name](Author URL)**.
Part of the [Infinito.Nexus Project](https://s.infinito.nexus/code) and maintained by [Kevin Veen-Birkenbach](https://www.veen.world).
Licensed under the [Infinito.Nexus Community License (Non-Commercial)](https://s.infinito.nexus/license).

Author name MUST equal galaxy_info.author in the role's meta/main.yml (the author single point of truth). It MAY be wrapped in a Markdown link as shown, or left as plain bold text (Implemented by **Author name**.) when no author URL applies.

Formatting Rules 📏

Role README files MUST NOT use emojis in headings. Emojis in role READMEs interfere with automated tooling that parses heading text.
Body text MAY use emojis where they improve readability.
All headings MUST use sentence-case (capitalize only the first word and proper nouns).
Link text MUST follow the link rules in documentation.md.

4.5 KiB Raw Permalink Blame History