Add yamllint check for RST code listings (#2385)

* Add yamllint check for RST code listings.

* Address review comments.

* Sort languages and remove no longer needed duplicates.

* Enable warnings, but disable all failing rules.

* Improve formulation.

Co-authored-by: Don Naro <[email protected]>

* Show allowed languages when no or invalid language is supplied. Improve line lengths.

* Make sure that 'yamllint .' passes.

* Fix indentation issues introduced in #2095.

---------

Co-authored-by: Don Naro <[email protected]>

Author: felixfontein

.github/workflows/build-package-docs.yaml

@@ -1,6 +1,6 @@
 ---
 name: Build and deploy docs
-on:
+"on":
   schedule:
     # Run at 05:17 on Tuesday and Thursday
     - cron: '17 5 * * 2,4'

.github/workflows/ci.yaml

@@ -1,8 +1,8 @@
 name: Ansible Docsite CI
 
-on:
+"on":
   schedule:
-    # Daily 
+    # Daily
     - cron: "23 7 * * *"
   push:
     branches-ignore:

.github/workflows/reusable-nox.yml

@@ -25,6 +25,8 @@ jobs:
             python-versions: "3.11"
           - session: "checkers(rstcheck)"
             python-versions: "3.11"
+          - session: "checkers(rst-yamllint)"
+            python-versions: "3.11"
           - session: "checkers(docs-build)"
             python-versions: "3.11"
           - session: "actionlint"

.mypy.ini

@@ -3,3 +3,6 @@ check_untyped_defs = True
 
 [mypy-ansible.*]
 ignore_missing_imports = True
+
+[mypy-yamllint.*]
+ignore_missing_imports = True

.yamllint

@@ -0,0 +1,68 @@
+---
+extends: default
+
+ignore:
+  - /lib/ansible/
+
+rules:
+  line-length: disable
+    # max: 160
+    # level: warning
+  document-start: disable
+  document-end: disable
+  truthy:
+    level: warning
+    allowed-values:
+      - 'true'
+      - 'false'
+      - 'True'
+      - 'False'
+      - 'TRUE'
+      - 'FALSE'
+      - 'yes'
+      - 'no'
+      - 'Yes'
+      - 'No'
+      - 'YES'
+      - 'NO'
+  indentation: disable
+    # level: warning
+    # spaces: 2
+    # indent-sequences: consistent
+  key-duplicates: disable
+    # level: warning
+    # forbid-duplicated-merge-keys: true
+  trailing-spaces: enable
+  hyphens: disable
+    # max-spaces-after: 1
+    # level: warning
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+    level: warning
+  commas: disable
+    # max-spaces-before: 0
+    # min-spaces-after: 1
+    # max-spaces-after: 1
+    # level: warning
+  colons: disable
+    # max-spaces-before: 0
+    # max-spaces-after: 1
+    # level: warning
+  brackets: disable
+    # min-spaces-inside: 0
+    # max-spaces-inside: 0
+    # level: warning
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+    level: warning
+  octal-values: disable
+    # forbid-implicit-octal: true
+    # forbid-explicit-octal: true
+    # level: warning
+  comments: disable
+    # min-spaces-from-content: 1
+    # level: warning
+  comments-indentation: disable

docs/docsite/rst/getting_started_ee/yaml/hosts.yml

@@ -1,3 +1,3 @@
 all:
   hosts:
-    192.168.0.2  # Replace with the IP of your target host
+    192.168.0.2  # Replace with the IP of your target host

docs/docsite/rst/playbook_guide/playbooks_error_handling.rst

@@ -179,16 +179,16 @@ You can reference simple variables in conditionals to avoid repeating certain te
   - name: Example playbook
     hosts: myHosts
     vars:
-       log_path: /home/ansible/logfolder/
-       log_file: log.log
+      log_path: /home/ansible/logfolder/
+      log_file: log.log
 
-   tasks:
+    tasks:
       - name: Create empty log file
-       ansible.builtin.shell: mkdir {{ log_path }} || touch {{log_path }}{{ log_file }}
-       register: tmp
-       changed_when:
-         - tmp.rc == 0
-         - 'tmp.stderr != "mkdir: cannot create directory ‘" ~ log_path ~ "’: File exists"'
+        ansible.builtin.shell: mkdir {{ log_path }} || touch {{log_path }}{{ log_file }}
+        register: tmp
+        changed_when:
+          - tmp.rc == 0
+          - 'tmp.stderr != "mkdir: cannot create directory ‘" ~ log_path ~ "’: File exists"'
 
 .. note::
    Notice the missing double curly braces ``{{ }}`` around the ``log_path`` variable in the ``changed_when`` statement. 

examples/DOCUMENTATION.yml

@@ -22,15 +22,15 @@ options:
         default: a string or the word null
         choices:
           - enable
-          - disable  
+          - disable
         aliases:
           - repo_name
         version_added: "1.X"
 requirements:
     - list of required things
     - like the factor package
-    - zypper >= 1.0        
-seealso: 
+    - zypper >= 1.0
+seealso:
    - specify references to other modules, useful guides, and so on
 notes:
     - other things consumers of your module should know

noxfile.py

@@ -15,6 +15,7 @@
     "hacking/tagger/tag.py",
     "noxfile.py",
     *iglob("docs/bin/*.py"),
+    *iglob("tests/checkers/rst-yamllint*.py"),  # TODO: also lint others
 )
 PINNED = os.environ.get("PINNED", "true").lower() in {"1", "true"}
 nox.options.sessions = ("clone-core", "lint", "checkers", "make")

tests/checkers/rst-yamllint.json

@@ -0,0 +1,9 @@
+{
+    "extensions": [
+        ".rst",
+        ".txt"
+    ],
+    "ignore_regexs": [
+        "^docs/docsite/rst/porting_guides/porting_guide_[0-9]+\\.rst$"
+    ]
+}