fix(docs): let docutils read these docstrings and two markdown files

Three shapes of the same failure, taken from the build's own message list
rather than from a reading pass.

Eight unescaped inline characters in prose: a '*', '**', backtick or '|'
opens markup that never closes. 'roles/*/vars/main.yml', the regex
'^(web-|svc-).*', 'scripts/system/tls/trust/*.sh'. In ansible_log an inline
literal ended on a space, which reStructuredText forbids; the space carried
meaning, so it moved into the prose.

Thirteen example blocks after a single ':', which makes the indented block
a block quote instead of a literal one.

Three bullet lists with no blank line to the paragraph above, which
docutils reads as a continuation of that paragraph.

Two markdown files carried a '---' where reStructuredText allows no
transition: directly after a heading, and at the end of a document.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

cli/administration/deploy/dedicated/proc.py

@@ -28,8 +28,9 @@ def run_make(repo_root: str, *targets: str) -> None:
     """
     Run `make <targets...>` from the repo root.
 
-    This prevents errors like:
-      make: *** No rule to make target 'clean'.  Stop.
+    This prevents errors like::
+
+        make: *** No rule to make target 'clean'.  Stop.
     """
     final_targets = targets or ("help",)
     run(["make", *final_targets], cwd=repo_root, check=True)

cli/administration/inventory/provision/filters.py

@@ -5,7 +5,8 @@ from typing import Any
 
 def parse_roles_list(raw_roles: list[str] | None) -> set[str] | None:
     """
-    Parse a list of IDs supplied on the CLI. Supports:
+    Parse a list of IDs supplied on the CLI. Supports::
+
       --include web-app-nextcloud web-app-mastodon
       --include web-app-nextcloud,web-app-mastodon
     Same logic is reused for --exclude and --roles.
@@ -50,7 +51,8 @@ def filter_dynamic_inventory(
     legacy_roles_filter: set[str] | None,
 ) -> dict[str, Any]:
     """
-    Apply include/exclude/legacy role filters in the same order as before:
+    Apply include/exclude/legacy role filters in the same order as before::
+
       include -> exclude -> legacy roles
     """
     if include_filter:

cli/build/docs/readme/cosmos.py

@@ -241,7 +241,7 @@ def _service_stopped(entry: dict) -> bool:
 
 
 def derive_cosmos_mermaid(role_dir: Path, role_name: str) -> str:
-    """Return a mermaid ``flowchart`` source (no ``` fences) for the role."""
+    """Return a mermaid ``flowchart`` source (no code fences) for the role."""
     role_dir = Path(role_dir)
     meta = _roles_meta(str(role_dir.parent))
     services = meta.get(role_name)

cli/build/docs/readme/overview.py

@@ -1,6 +1,7 @@
 """Generate the invokable-role overview table in the repository README.
 
-Usage:
+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
@@ -11,7 +12,8 @@ sorted ascending by the Entity column.
 Rows are the invokable roles inside the tested lifecycle envelope, sorted
 ascending by name.
 
-Columns:
+Columns::
+
   Name             Role README H1 title, linked to the role directory.
   Status           Role lifecycle stage.
   Description      ``galaxy_info.description`` from meta/main.yml.

cli/build/graph/__main__.py

@@ -54,8 +54,10 @@ def find_role_tasks(roles_dir: str, role: str) -> str:
 
 def load_meta(path: str) -> Dict[str, Any]:
     """
-    Load metadata from meta/main.yml.
+    Load metadata from ``meta/main.yml``.
+
     Returns a dict with:
+
         - galaxy_info
         - run_after 
         - dependencies
@@ -209,6 +211,7 @@ def build_mappings(
     """
     Build all 12 graph variants (6 dep types × 2 directions).
     Accelerated version:
+
         - One-time scan of all metadata
         - One-time scan of all include_role/import_role
         - One-time scan of include_tasks/import_tasks

plugins/filter/active_docker.py

@@ -4,7 +4,7 @@ Ansible filter to count active docker services for current host.
 Active means:
 
 - application key is in group_names
-- application key matches prefix regex (default: ^(web-|svc-).* )
+- application key matches prefix regex (default: ``^(web-|svc-).*``)
 - under applications[app]['services'] each service is counted if:
 
   - 'enabled' is True, OR

plugins/filter/get/all/application_ids.py

@@ -10,7 +10,7 @@ from utils.roles.mapping import ROLE_FILE_VARS_MAIN
 def get_all_application_ids(roles_dir="roles"):
     """
     Ansible filter to retrieve all unique application_id values
-    defined in roles/*/vars/main.yml files.
+    defined in ``roles/*/vars/main.yml`` files.
 
     :param roles_dir: Base directory for Ansible roles (default: 'roles')
     :return: Sorted list of unique application_id strings

plugins/filter/role_path_by_app_id.py

@@ -46,7 +46,7 @@ def _role_path_by_application_id(application_id, index):
 
 def abs_role_path_by_application_id(application_id):
     """
-    Searches all roles/*/vars/main.yml for application_id and returns
+    Searches all ``roles/*/vars/main.yml`` for application_id and returns
     the absolute path of the role that matches. Raises an error if
     zero or more than one match is found.
     """
@@ -55,7 +55,7 @@ def abs_role_path_by_application_id(application_id):
 
 def rel_role_path_by_application_id(application_id):
     """
-    Searches all roles/*/vars/main.yml for application_id and returns
+    Searches all ``roles/*/vars/main.yml`` for application_id and returns
     the relative path (from the project root) of the role that matches.
     Raises an error if zero or more than one match is found.
     """

plugins/filter/url/join.py

@@ -1,11 +1,14 @@
 """
 Ansible filter plugin that safely joins URL components from a list.
+
 - Requires a valid '<scheme>://' in the first element (any RFC-3986-ish scheme)
 - Preserves the double slash after the scheme, collapses other duplicate slashes
 - Supports query parts introduced by elements starting with '?' or '&'
+
   * first query element uses '?', subsequent use '&' (regardless of given prefix)
   * each query element must be exactly one 'key=value' pair
   * query elements may only appear after path elements; once query starts, no more path parts
+
 - Raises specific AnsibleFilterError messages for common misuse
 """
 

plugins/lookup/container_address.py

@@ -27,7 +27,7 @@ non-manager nodes (exit 64) and reports clear errors when the service
 has no running task (exit 65) or the task is not yet bound to a
 container (exit 66).
 
-Examples:
+Examples::
 
     # roles/web-app-X/vars/main.yml
     X_CONTAINER_ADDRESS: "{{ lookup('container_address', application_id, 'x') }}"

plugins/lookup/depends_on.py

@@ -13,7 +13,7 @@ Hand-writing the ``{% if DEPLOYMENT_MODE == 'swarm' %} … {% else %} …
 gate, wrong condition default, inconsistent indent). This lookup
 emits the whole block and switches on ``DEPLOYMENT_MODE`` itself.
 
-USAGE
+USAGE::
 
     # One dependency with an explicit condition.
     {{ lookup('depends_on', {ERPNEXT_CONFIGURATOR_CONTAINER:

plugins/lookup/fediwall_active.py

@@ -12,7 +12,8 @@ active on the current host (i.e. its application_id is in
     url_bases  -> each sibling's TLS ``url.base``
                   (= the same value ``lookup('tls', s, 'url.base')`` returns)
 
-Used by:
+Used by::
+
     meta/server.yml                  -> connect-src CSP whitelist (url_bases)
     templates/wall-config.json.j2    -> default ``servers`` list   (domains)
 

plugins/lookup/node_max_old_space_size.py

@@ -1,13 +1,14 @@
 """Derive a Node.js ``--max-old-space-size`` (MB) from a service's mem_limit.
 
 Lookup form — the app config is resolved internally, so callers no longer pipe
-``lookup('applications')`` in:
+``lookup('applications')`` in::
 
     {{ lookup('node_max_old_space_size', application_id, service_name) }}
     {{ lookup('node_max_old_space_size', application_id, service_name,
               pct=0.125, min_mb=256, hardcap_mb=1024) }}
 
 Heuristics (defaults):
+
   - candidate = 35% of mem_limit
   - min       = 768 MB (required minimum)
   - cap       = min(3072 MB, 60% of mem_limit)

plugins/lookup/postgres_libraries.py

@@ -1,12 +1,14 @@
 """Resolve postgres-extension library install recipes.
 
-Usage:
+Usage::
+
   {{ lookup('postgres_libraries', ['vector', 'bloom']) }}
 
 Takes a list of extension names and returns the subset that needs a
 custom library install on top of the official postgres base image
 (the contrib extensions bloom, pg_trgm and unaccent are already in the
 base — those are filtered out). Each returned entry is a dict with:
+
   - extension: the extension name (matches the SQL identifier)
   - name:      the library/source name (used in the Dockerfile context)
   - apt_package: the PGDG package suffix, installed as

plugins/lookup/shared_network_key.py

@@ -8,7 +8,7 @@ claim the rendered file does not make. The key is derived from
 ``utils.networks.render``, which renders the file itself, so the two cannot
 drift.
 
-Examples:
+Examples::
 
     - name: create the shared network
       ansible.builtin.command:

roles/sys-token-store/README.md

@@ -106,8 +106,6 @@ Empty tokens are rejected explicitly.
 
 ## Usage Examples
 
----
-
 ### Persist a token
 
 ```yaml

scripts/system/systemd/README.md

@@ -12,5 +12,3 @@ For the canonical Make target index that invokes these helpers, see [make.md](..
 Platform-specific scripts for enabling systemd where it is not active by default.
 
 - **`wsl2.sh`**. enables systemd as the WSL2 init system via `/etc/wsl.conf` and restarts WSL2 if needed
-
----

utils/ansible_log.py

@@ -1,7 +1,7 @@
 """SPOT for the line prefix Ansible writes into its ``log_path`` file.
 
 Every line of the file named by ``ANSIBLE_LOG_PATH`` carries
-``<ts> p=<pid> u=<user> n=<name> <LEVEL>| `` in front of the message that
+``<ts> p=<pid> u=<user> n=<name> <LEVEL>|`` and a space in front of the message that
 also went to stdout. Left unstripped, that prefix defeats every
 line-anchored matcher a reader applies, so a reader that mixes an anchored
 match with an unanchored one silently sees an empty log instead of failing.

utils/docker/image/discovery.py

@@ -188,9 +188,9 @@ def canonical_image_name(image: str) -> str:
 
 def iter_role_images(repo_root: Path) -> Iterable[ImageRef]:
     """
-    Yield all ImageRef entries discovered across all roles in *repo_root*.
+    Yield all ImageRef entries discovered across all roles in ``repo_root``.
 
-    Source: roles/**/meta/services.yml → <entity>.{image,version}.
+    Source: ``roles/**/meta/services.yml`` -> ``<entity>.{image,version}``.
 
     See docs/contributing/artefact/image.md for the full format reference.
     """

utils/env/handlers/infinito/ca/cert_host.py

@@ -1,7 +1,7 @@
 """INFINITO_CA_CERT_HOST: host path of the self-signed root CA cert.
 
 Derived from the ca_trust_paths SPOT plus SOFTWARE_NAME (group_vars); consumed
-by scripts/system/tls/trust/*.sh so the path never lives in shell literals.
+by ``scripts/system/tls/trust/*.sh`` so the path never lives in shell literals.
 SOFTWARE_NAME is line-parsed instead of yaml-loaded: the env generator runs on
 the bare bootstrap python before any dependency (PyYAML) is installed.
 """

utils/roles/applications/mcp.py

@@ -21,6 +21,7 @@ Field vocabulary (see ``docs/contributing/design/role/services/mcp.md``):
 * ``implementation``:  how the surface is provided, ordered by precedence.
 * ``credential``:      which principal the provider authenticates as, and
   where its secret is read from. Replaces the administrator token path.
+
 Admission is not declared here. A client marks itself once, in its own
 ``meta/services.yml`` self-entry, as ``mcp_consumer: true``; a provider
 deviates by carrying ``mcp_consumer: false`` on that client's entry in its

utils/roles/applications/services/sso.py

@@ -86,7 +86,8 @@ def get_sso_config(
 ) -> dict[str, Any]:
     """Resolve the SSO state for a consumer role.
 
-    Returns a dict with keys:
+    Returns a dict with keys::
+
         enabled                 bool — ``services.sso.enabled``
         shared                  bool — ``services.sso.shared``
         flavor                  str  — one of {oidc, oauth2, saml}; default 'oidc'

utils/roles/applications/topics.py

@@ -2,7 +2,7 @@
 
 A round deploys a provider once, so the role that pulls it in is the only
 place that can say how lean it has to be. A variant entry may therefore carry
-any application config topic under the service it depends on:
+any application config topic under the service it depends on::
 
     services:
       openwebui:

utils/roles/validation/invokable.py

@@ -138,7 +138,8 @@ def list_invokables_by_type(
     skip_mode: str | None = None,
 ) -> dict[str, list[str]]:
     """
-    Returns:
+    Returns::
+
       {
         "server": [...],
         "workstation": [...],
@@ -203,10 +204,12 @@ def types_from_group_names(
 ) -> list[str]:
     """
     SPOT:
+
       - invokable is defined by categories.yml via _get_invokable_paths()/_is_role_invokable()
       - server/workstation/universal classification is defined by DEFAULT_RULES
 
-    Semantics:
+    Semantics::
+
       universal = invokable AND NOT matched by any non-universal rule.
     """
     names = [str(g).strip() for g in (group_names or []) if str(g).strip()]

utils/tls_common.py

@@ -60,8 +60,10 @@ def want_get(data: Any, dotted: str) -> Any:
 
 def iter_domains(value: Any) -> Iterable[str]:
     """
-    Flatten domains from the *global* domains mapping entry.
+    Flatten domains from the global domains mapping entry.
+
     Supports:
+
       - str
       - list[str]
       - dict[str, str]   (only one level, legacy behavior)
@@ -193,13 +195,15 @@ def resolve_term(
     Returns (app_id, primary_domain) where primary_domain is normalized lower-case.
 
     term can be:
+
       - application_id
       - domain (canonical or alias)
 
     forced_mode: "auto" | "domain" | "app"
 
-    Behavior:
-      1) If term is a domain and exists in *global* domains mapping -> primary_domain = that term (normalized).
+    Behavior::
+
+      1) If term is a domain and exists in the global domains mapping -> primary_domain = that term (normalized).
       2) If term is a domain and only exists in applications[*].domains -> map to app_id,
          and primary_domain = canonical primary from global domains mapping (first entry).
     """