Improve the documentation of logstash role

.docsmith/readme.md.j2

@@ -0,0 +1,23 @@
+{# Compact README variable reference for ansible-docsmith. Shared by all roles.
+   Renders ONE table; nested sub-options (e.g. logstash_pipelines fields) appear as
+   indented rows. No per-variable detail sections, no table of contents.
+   Use with: --template-readme .docsmith/readme.md.j2 #}
+{% macro row(name, spec, depth) -%}
+{% set pad = '    ' * depth %}
+{% set mark = '↳ ' if depth > 0 else '' %}
+| {{ pad }}{{ mark }}`{{ name | ansible_escape }}` | `{{ spec.type }}`{% if spec.elements %} of `{{ spec.elements }}`{% endif %} | {% if spec.options %}…{% else %}{{ spec.default | format_default }}{% endif %} | {% if spec.choices %}{{ spec.choices | map('string') | map('code_escape') | join(', ') }}{% else %}—{% endif %} | {{ spec.description | format_table_description(name, 0) }} |
+{% for sn, ss in (spec.options or {}).items() %}
+{{ row(sn, ss, depth + 1) }}
+{%- endfor %}
+{%- endmacro %}
+## Role variables<a id="variables"></a>
+
+{% if has_options %}
+| Variable | Type | Default | Choices | Description |
+|----------|------|---------|---------|-------------|
+{% for name, spec in options.items() %}
+{{ row(name, spec, 0) }}
+{%- endfor %}
+{% else %}
+No variables are defined for this role.
+{% endif %}

.github/workflows/test_docs.yml

@@ -0,0 +1,73 @@
+---
+name: Test Documentation
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'roles/**/meta/argument_specs.yml'
+      - 'roles/**/defaults/**'
+      - 'roles/**/README.md'
+      - '.docsmith/**'
+      - '.github/workflows/test_docs.yml'
+
+# Cancel outdated pipeline runs when a new push occurs in the pull request.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    # For non-PR events (workflow_dispatch, etc.), github.event.pull_request.draft is null.
+    # GitHub Actions coerces null == false to true, so the job runs for all non-draft events.
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    env:
+      NO_COLOR: "1"  # make ansible-docsmith print plain text so grep is reliable
+    steps:
+      - name: Check out the codebase.
+        uses: actions/checkout@v6
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      # Pin the version: ansible-docsmith is a young tool, so we
+      # upgrade deliberately rather than picking up changes on every CI run.
+      - name: Install ansible-docsmith
+        run: python3 -m pip install ansible-docsmith==2.0.2
+
+      # Consistency between meta/argument_specs.yml and defaults/main.yml.
+      # validate exits 1 on ERROR by itself; here we additionally treat any
+      # WARNING (e.g. a default that differs between spec and defaults) as a failure.
+      - name: Validate argument_specs (warnings = errors)
+        run: |
+          set -uo pipefail
+          status=0
+          for role in roles/*/; do
+            [ -f "${role}meta/argument_specs.yml" ] || continue
+            echo "::group::validate ${role}"
+            out=$(ansible-docsmith validate "${role}" 2>&1) && rc=0 || rc=$?
+            echo "$out"
+            echo "::endgroup::"
+            if [ "$rc" -ne 0 ] || grep -q "Warnings:" <<<"$out"; then
+              echo "::error::ansible-docsmith reported errors or warnings for ${role}"
+              status=1
+            fi
+          done
+          exit $status
+
+      # README freshness: regenerate every role README and fail if anything changed,
+      # i.e. the committed README no longer matches argument_specs.yml.
+      - name: Check that every variable in README is up to date
+        run: |
+          for role in roles/*/; do
+            [ -f "${role}meta/argument_specs.yml" ] || continue
+            ansible-docsmith generate "${role}" --no-defaults \
+              --template-readme .docsmith/readme.md.j2
+          done
+          git diff --exit-code -- 'roles/*/README.md' || {
+            echo "::error::A role README is out of date. Run locally:";
+            echo "  ansible-docsmith generate <role> --no-defaults --template-readme .docsmith/readme.md.j2";
+            exit 1;
+          }

.github/workflows/test_role_logstash.yml

@@ -15,6 +15,7 @@ on:
   pull_request:
     paths:
       - 'roles/logstash/**'
+      - '!roles/logstash/**/*.md'
       - '.github/workflows/test_role_logstash.yml'
       - 'molecule/logstash_**'
 

.github/workflows/test_roles_pr.yml

@@ -15,6 +15,8 @@ on:
   pull_request:
     paths:
       - 'roles/**'
+      - '!roles/**/*.md'
+      - '!roles/**/meta/argument_specs.yml'
       - 'molecule/elasticstack_default/**'
       - 'requirements-test.txt'
       - '.github/workflows/test_roles_pr.yml'

README.md

@@ -15,7 +15,7 @@ Every role is documented with all variables, please refer to the documentation f
 * [Beats](docs/role-beats.md)
 * [Elasticsearch](docs/role-elasticsearch.md)
 * [Kibana](docs/role-kibana.md)
-* [Logstash](docs/role-logstash.md)
+* [Logstash](roles/logstash/README.md)
 * [Repos](docs/role-repos.md)
 
 ## Modules documentation
@@ -226,6 +226,25 @@ Every kind of contribution is very welcome. Open [issues](https://github.com/NET
 
 For now we open pull requests against `main`. We are planning to introduce dedicated branches to support older versions without breaking changes. Since we don't need them for now, please check back with this section because when we decided on how to proceed, you will find the information here. For now `main` always has the newest changes and if you want a stable version, please use the newest release.
 
+### Documentation for role variables
+
+Role variables are documented from each role's `meta/argument_specs.yml`, which is
+the single source of truth. When your pull request changes a role's variables:
+
+1. Update that role's `meta/argument_specs.yml` (type, default, description).
+2. Regenerate the README variable table — please do **not** edit it by hand. The table is
+   produced by [ansible-docsmith](https://github.com/foundata/ansible-docsmith)
+   (install with `pip install ansible-docsmith` if you don't have it):
+
+   ```
+   ansible-docsmith generate roles/<role> --no-defaults --template-readme .docsmith/readme.md.j2
+   ```
+
+3. Commit the regenerated `README.md` together with your change.
+
+The `Test Documentation` workflow checks that each README matches its
+`argument_specs.yml` and fails the pull request if they drift apart.
+
 ## Testing
 
 Besides real tests that the developer should do before creating a PR, we built molecule scenarios to test the complete stack.

RELEASE.md

@@ -8,10 +8,28 @@
 
 Remove the note above saying that this is a work and progress before the first release. And remove this section.
 
+### Lint
+
+Make sure to have one last pull request to remove as much lint as possible. Same goes for deprecation warnings, linter exceptions etc.
+
 ### Authors
 
 Update the [.mailmap](.mailmap) and [AUTHORS](AUTHORS) files:
 
 ```
 git log --use-mailmap | grep '^Author:' | cut -f2- -d' ' | sort | uniq > AUTHORS
 ```
+
+## Tag
+
+Tag the version. Don't use `v` in the name. Use semantic versioning.
+
+e.g.
+
+```
+git tag -as 7.6.4
+```
+
+## Release
+
+Make the tag a release on GitHub.

docs/getting-started.md

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