Add docs building and testing

- Allows local build using tox -e docs - Builds docs using GHA - Builds and publishes docs using RTD (including PRs)
ansible · Aug 21, 2024 · 297de0f · 297de0f
1 parent a92be59
commit 297de0f
Show file tree

Hide file tree

Showing 26 changed files with 7,494 additions and 24 deletions.
diff --git a/.config/dictionary.txt b/.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
diff --git a/.github/workflows/tox.yml b/.github/workflows/tox.yml
@@ -37,11 +37,11 @@ jobs:
           min_python: "3.9"
           max_python: "3.12"
           default_python: "3.9"
-          # Wwe run sanity with 3 different versions of ansible as the result
+          # We run sanity with 3 different versions of ansible as the result
           # 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
@@ -130,6 +130,9 @@ jobs:
       - run: ${{ matrix.command4 }}
         if: ${{ matrix.command4 }}
 
+      - run: ${{ matrix.command5 }}
+        if: ${{ matrix.command5 }}
+
       - name: Archive logs
         uses: actions/upload-artifact@v4
         with:

diff --git a/.gitignore b/.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
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -11,7 +11,10 @@ ci:
     - ansible-test-sanity # requires network access
     - shellcheck  # no docker
     - tox # requires network access
-exclude: "^.*\\.md$"
+exclude: >
+  (?x)^(
+    docs/rst/.*.rst$
+  )$
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,26 @@
+# .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-24.04
+  tools:
+    python: "3.12"
+  # 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:
+    # Copy executable in the first directory in path, which happens to be writable on RTD
+    - mkdir -p ${PATH%%:*}
+    - cp docs/bin/rsync ${PATH%%:*}/
+    - rsync --version
+    - pip install --user tox
+    - python3 -m tox -e docs
+    - mkdir -p $READTHEDOCS_OUTPUT
+    - cp -r docs/build/html ${READTHEDOCS_OUTPUT}/
diff --git a/bindep.txt b/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]

diff --git a/demos/dynatrace-demo/instructions.md b/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`

diff --git a/docs/.gitignore b/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
diff --git a/docs/bin/README.md b/docs/bin/README.md
@@ -0,0 +1,2 @@
+This rsync static build binary is solely used on RTD build due to
+https://github.com/readthedocs/readthedocs.org/issues/9599
diff --git a/docs/bin/rsync b/docs/bin/rsync
diff --git a/docs/requirements.txt b/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