Rework repos role documentations

.github/workflows/test_role_repos.yml

@@ -14,6 +14,7 @@ on:
   pull_request:
     paths:
       - 'roles/repos/**'
+      - '!roles/repos/**/*.md'
       - '.github/workflows/test_role_repos.yml'
       - 'molecule/repos_**'
 

README.md

@@ -16,7 +16,7 @@ Every role is documented with all variables, please refer to the documentation f
 * [Elasticsearch](docs/role-elasticsearch.md)
 * [Kibana](docs/role-kibana.md)
 * [Logstash](roles/logstash/README.md)
-* [Repos](docs/role-repos.md)
+* [Repos](roles/repos/README.md)
 
 ## Modules documentation
 

docs/getting-started.md

@@ -51,7 +51,7 @@ Roles
 * [Elasticsearch](role-elasticsearch.md)
 * [Kibana](role-kibana.md)
 * [Logstash](../roles/logstash/README.md)
-* [Repos](role-repos.md)
+* [Repos](../roles/repos/README.md)
 
 
 Variables

docs/role-repos.md

@@ -1,43 +1,5 @@
-Elastic Repos
-=========
+# Repos role
 
-![Test Role repos](https://github.com/netways/ansible-collection-elasticstack/actions/workflows/test_role_repos.yml/badge.svg)
+The Repos role documentation now lives with the role itself:
 
-The role adds Elastic repositories to the package manager. It's main use is in connection with other roles that provide installation and configuration of the Elastic Stack.
-
-Requirements
-------------
-
-* You need `gpg` to be installed because packages / repositories are digitally signed and verified.
-* Debian and Ubuntu hosts need to have `apt-transport-https` installed to deal with Elastics repositories.
-* Ubuntu hosts also need to have `gpg-agent` installed.
-* For SuSE hosts you need the Ansible collection `community.general` on your Ansible controller.
-
-Role Variables
---------------
-
-* *elasticstack_release*: Major release version of Elastic stack to configure. (default: `7`). `7` and `8` are supported.
-* *elasticstack_variant*: Variant of the stack to install. Valid values: `elastic` or `oss`. (default: `elastic`).
-* *elasticstack_enable_repos*: Enable repositories after creating them. (default: `true`) Only works on RPM based distributions!
-
-Please note that no `oss` versions are available for Elastic Stack later than `7`. This role will fail if you try to install them.
-
-Usage
---------
-
-Upgrades
-========
-
-If you want to be able to update your operating system without worrying about accidentally upgrading Elastic Stack, set `elasticstack_enable_repos` to `false`. The roles in this collection will enable the repository in case they need it. Keep in mind that this will only work on rpm based distributions.
-
-Example playbook
-================
-
-```
-  - hosts: all
-    become: yes
-    collections:
-      - netways.elasticstack
-    roles:
-      - repos
-```
+**➜ [roles/repos/README.md](../roles/repos/README.md)**

roles/repos/README.md

@@ -0,0 +1,42 @@
+# Ansible Role: Repos
+
+Adds the Elastic package repositories to the target host so the other roles can
+install Elastic Stack packages. It supports apt (Debian/Ubuntu), yum (RedHat) and
+zypper (SUSE), for both the standard Elastic and the OSS variant.
+
+Its main use is together with the other roles of this collection, which expect
+the Elastic repositories to be present.
+
+## Requirements
+
+* The `community.general` collection — only needed on SUSE hosts, where the role
+  uses the `zypper` modules.
+* Network access from the target host to the Elastic repository URL.
+
+The role installs the required signing tools (`gpg`/`gnupg`) itself.
+
+## Example
+
+```yaml
+- name: Configure Elastic repositories
+  hosts: all
+  collections:
+    - netways.elasticstack
+  roles:
+    - repos
+```
+
+<!-- ANSIBLE DOCSMITH MAIN START -->
+## Role variables<a id="variables"></a>
+
+No variables are defined for this role.
+
+<!-- ANSIBLE DOCSMITH MAIN END -->
+
+## Shared variables
+
+This role is configured through the collection-wide `elasticstack_*` variables —
+mainly `elasticstack_release`, `elasticstack_variant`, `elasticstack_enable_repos`,
+`elasticstack_repo_url`, `elasticstack_repo_key` and `elasticstack_rpm_workaround`.
+They are documented centrally with the
+[elasticsearch role](../../docs/role-elasticsearch.md).

roles/repos/meta/argument_specs.yml

@@ -0,0 +1,20 @@
+---
+# Role argument specification for the repos role.
+# This is the single source of truth for the role's variables: Ansible validates
+# the supplied values against it at role start, and ansible-docsmith renders the
+# README variable reference from it.
+#
+# This role has no role-specific variables. It is configured entirely through the
+# shared elasticstack_* variables, which are documented centrally with the
+# elasticstack role.
+
+argument_specs:
+  main:
+    short_description: Configure the Elastic package repositories
+    description:
+      - >-
+        Adds the Elastic package repositories (apt, yum or zypper) to the target
+        host so the other roles can install Elastic Stack packages.
+      - Supports the standard Elastic and the OSS variant.
+    author:
+      - NETWAYS GmbH