Add docs building and testing

- Allows local build using tox -e docs
- Builds docs using GHA
- Builds and publishes docs using RTD (including PRs)

.config/dictionary.txt

@@ -1,16 +1,31 @@
 -CAcreateserial
 -Djava
+ARGSPEC
+AUTHS
+Abhijeet
+Alina
+Buzachis
+EDAHTTP
+FQCN
 GSSAPI
+Kasurde
+Nikhil
 OAUTHBEARER
 PYTHONUNBUFFERED
+Passw
+akasurde
 alertmanager
+alinabuzachis
+antsibull
+auths
 basepython
 benthomasosn
 bindep
 buildx
 cafile
 capath
 caroot
+cliconf
 confluentinc
 conninfo
 containerd
@@ -21,19 +36,25 @@ dynatrace
 envlist
 extfile
 finito
+hdrs
 healthcheck
+httpapi
 jaas
+jainnikhil
+keygen
 keypass
 keytool
 libsystemd
 mydb
 myqueue
 nada
+netconf
 noprompt
 parseable
 posargs
 pythonmain
 realworld
+refspec
 rulebook
 rulebooks
 ruleset
@@ -42,24 +63,8 @@ skipsdist
 snakeoil
 storepass
 testenv
+testsecret
+testuser
 toxinidir
 trustore
 truststore
-ARGSPEC
-Nikhil
-jainnikhil
-Abhijeet
-Kasurde
-akasurde
-auths
-Passw
-AUTHS
-EDAHTTP
-refspec
-Alina
-Buzachis
-alinabuzachis
-hdrs
-testuser
-testsecret
-keygen

.github/workflows/tox.yml

@@ -41,7 +41,7 @@ jobs:
           # can be different. Each of them is testing with all supported
           # python versions, regardless the tox pyXY name.
           other_names: |
-            lint-sanity:tox -e lint;tox -e py39-sanity-ansible2.15;tox -e py310-sanity-ansible2.16;tox -e py311-sanity-ansible2.17
+            lint-docs-sanity:tox -e lint;tox -e docs;tox -e py39-sanity-ansible2.15;tox -e py310-sanity-ansible2.16;tox -e py311-sanity-ansible2.17
             py39:tox -e py39-unit;tox -e py39-integration;tox -e coverage
             py310:tox -e py310-unit; tox -e py310-integration;tox -e coverage
             py311:tox -e py311-unit; tox -e py311-integration;tox -e coverage
@@ -57,6 +57,7 @@ jobs:
     runs-on: ${{ matrix.os || 'ubuntu-24.04' }}
     continue-on-error: ${{ contains(matrix.name, 'integration') && true || false }}
     needs:
+      - docs
       - prepare
     defaults:
       run:
@@ -130,6 +131,9 @@ jobs:
       - run: ${{ matrix.command4 }}
         if: ${{ matrix.command4 }}
 
+      - run: ${{ matrix.command5 }}
+        if: ${{ matrix.command5 }}
+
       - name: Archive logs
         uses: actions/upload-artifact@v4
         with:
@@ -150,6 +154,15 @@ jobs:
             exit 99
           fi
         # https://github.com/actions/toolkit/issues/193
+  docs:
+    permissions:
+      contents: read
+    name: Validate Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-pr.yml@main
+    with:
+      collection-name: ansible.eda
+      init-lenient: false
+      init-fail-on-error: true
   check:
     if: always()
     environment: check

.gitignore

@@ -24,3 +24,7 @@ tests/integration/event_source_kafka/*.jks
 # Coverage
 .coverage*
 *coverage.combined
+# docs/requirements.txt
+docs/build.sh
+docs/antsibull-docs.cfg
+docs/conf.py

.pre-commit-config.yaml

@@ -11,7 +11,11 @@ ci:
     - ansible-test-sanity # requires network access
     - shellcheck  # no docker
     - tox # requires network access
-exclude: "^.*\\.md$"
+exclude: >
+  (?x)^(
+    docs/rst/.*.rst$|
+    test/fixtures/formatting-before/.*
+  )$
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0

.readthedocs.yaml

@@ -0,0 +1,28 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04 # default py310
+  tools:
+    python: "3.10"
+  # When using commands we canon install apt_package due to
+  # https://github.com/readthedocs/readthedocs.org/issues/11219
+  # https://github.com/readthedocs/readthedocs.org/issues/9599
+  # apt_packages:
+  #   - rsync
+  commands:
+    - echo $PATH
+    - curl -o /tmp/rsync.tar.gz https://download.samba.org/pub/rsync/binaries/ubuntu-22.04-x86_64/rsync-3.2.7.tar.gz
+    - tar -xzf /tmp/rsync.tar.gz -C /tmp
+    # Copy executable in the first directory in path, which happens to be writable on RTD
+    - mkdir -p ${PATH%%:*}
+    - cp /tmp/usr/local/bin/rsync ${PATH%%:*}/
+    - rsync --version
+    - pip install --user tox
+    - python3 -m tox -e docs
+    - ln -s docs/build/html . $READTHEDOCS_OUTPUT/html/

bindep.txt

@@ -3,6 +3,9 @@ libsystemd0 [test platform:debian]
 libsystemd-dev [test platform:debian]
 pkg-config  [test platform:debian]
 
+# docs
+rsync [test platform:debian]
+
 # For sanity testing to pass we need all supported Python versions installed:
 python3.9-dev [test platform:ubuntu-noble]
 python3.9-venv [test platform:ubuntu-noble]

demos/dynatrace-demo/instructions.md

@@ -10,7 +10,7 @@ rulebook CLI runs a remedy playbook to restart the process.
 ### Nodes or instances
 * Rulebook Node: The node where the ansible-rulebook CLI is running
 * Client Node: The node where the monitored process is running
-* Dynatrace Console: An active Dyntrace tenant and its web console
+* Dynatrace Console: An active Dynatrace tenant and its web console
 
 ### Set up client node
 1. Prepare a VM with host name called `lamp`

docs/.gitignore

@@ -0,0 +1,8 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Created with antsibull-docs 2.12.0
+
+/temp-rst
+/build

docs/requirements.txt

@@ -0,0 +1,10 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Created with antsibull-docs 2.12.0
+
+antsibull-docs >= 2.0.0, < 3.0.0
+ansible-pygments
+sphinx
+sphinx-ansible-theme >= 0.9.0