Merge branch 'main' into remaining_recs

.github/workflows/make_docs.yml

@@ -2,30 +2,40 @@ name: publish document
 
 on:
   push:
-    tags:
-      - v*
+    branches:
+      - main
 
 jobs:
   build:
 
     runs-on: ubuntu-latest
+    container: fedora:latest
 
     steps:
-    - uses: actions/checkout@v3
-
     - name: Install requirements
-      run: sudo apt-get install asciidoctor ruby-asciidoctor-pdf
+      run: sudo dnf install -y git graphviz make plantuml rubygem-asciidoctor rubygem-asciidoctor-pdf rubygem-rouge
 
-    - name: Install requirements
+    - name: Repository checkout
+      uses: actions/checkout@v3
+
+    - name: Move to the correct folder
       run: cd $GITHUB_WORKSPACE
-
-    - name: render HTML
+
+    - name: Ensure git folder is considered safe
+      run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+    - name: Render HTML
       run: make release
-
-    - uses: stefanzweifel/git-auto-commit-action@v4
+
+    - name: Git add and force push to docs
+      run: git add -f docs
+
+    - name: Push changes
+      uses: stefanzweifel/git-auto-commit-action@v4
       with:
         commit_message: publish release
         file_pattern: docs/*
+        add_options: '-A --force'
         branch: docs  # main branch is protected, make sure this one is used for GitHub pages
         # the following options are necessary to forcefully overwrite each time the branch
         skip_fetch: true

.github/workflows/test_docs.yml

@@ -7,15 +7,20 @@ jobs:
   test-build-docs:
 
     runs-on: ubuntu-latest
+    container: fedora:latest
 
     steps:
-    - uses: actions/checkout@v3
-
     - name: Install requirements
-      run: sudo apt-get install asciidoctor ruby-asciidoctor-pdf
+      run: sudo dnf install -y git graphviz make plantuml rubygem-asciidoctor rubygem-asciidoctor-pdf rubygem-rouge
 
-    - name: Install requirements
+    - name: Repository checkout
+      uses: actions/checkout@v3
+
+    - name: Move to the correct folder
       run: cd $GITHUB_WORKSPACE
 
-    - name: render HTML
+    - name: Ensure git folder is considered safe
+      run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+    - name: Render HTML
       run: make release

.github/workflows/test_markdown_links.yml

@@ -0,0 +1,21 @@
+---
+# This action checks all Markdown files in the repository for broken links. 
+# (Uses https://github.com/tcort/markdown-link-check) 
+name: markdown link check
+
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'yes'
+          config-file: '.mlc_config.json'
+...

.gitignore

@@ -1,7 +1,9 @@
 # generated files
-*.pdf
 *.html
-!docs/*.html
+*.pdf
+*.png
+*.svg
+docs
 
 # temporary files
 .*.swp

Makefile

@@ -51,13 +51,20 @@ push: clean
 pull:
 	$(VCS) pull
 
-release:
+plantuml:
+	for f in images/*.plantuml; do \
+		plantuml $${f} -tsvg; \
+	done
+
+release: plantuml
+	mkdir -p docs
 	$(ADOCHTML) -D docs --out-file index.html $(INFILE)
 	$(ADOCHTML) -D docs --out-file CONTRIBUTE.html $(INFILE2)
 	mkdir -p docs/images
 	cp -v images/*.svg docs/images
 
 preview:
+	mkdir -p docs
 	$(ADOCPDF) --out-file docs/preview/$(OUTFILE).pdf $(INFILE)
 	$(ADOCPDF) --out-file docs/preview/$(OUTFILE2).pdf $(INFILE2)
 	$(ADOCHTML) --out-file docs/preview/$(OUTFILE).html $(INFILE)

_style/render.adoc

@@ -11,6 +11,9 @@
 :listing-caption: Listing
 :imagesdir: images/
 
+:revnumber: {gitdate} (commit: {githash})
+:!last-update-label:
+
 // The following lines could become relevant in the future
 
 ////

coding_style/README.adoc

@@ -89,7 +89,7 @@ TIP: use the sign `>-` if it is important that the last line return code doesn't
 +
 [%collapsible]
 ====
-Rationale:: Ansible will `and` the list elements together (https://docs.ansible.coansible/latest/user_guidplaybooks_conditionalhtml#the-when-statement[Ansible UseGuide » Conditionals]).
+Rationale:: Ansible will `and` the list elements together (https://docs.ansible.com/ansible/latest/user_guide/playbooks_conditionals.html#basic-conditionals-with-when[Ansible UseGuide » Conditionals]).
 Multiple conditions that all need to be true (a logical `and`) can also be specified as a list, but beware of bare variables in `when:`.
 Examples::
 +
@@ -198,7 +198,7 @@ Dot notation will fail in some cases (such as when a variable name includes a hy
 Additionally, some key names collide with attributes and methods of Python dictionaries such as `count`, `copy`, `title`, and others (refer to the https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#referencing-key-value-dictionary-variables[Ansible User Guide] for an extended list)
 
 Example::
-This https://blog.networktocode.com/post/Exploring-Jinja-Variable-Syntax-in-Ansible[post] provdes an excellent demonstration of how using dot notation syntax can impact your playbooks.
+This https://blog.networktocode.com/post/Exploring-Jinja-Variable-Syntax-in-Ansible[post] provides an excellent demonstration of how using dot notation syntax can impact your playbooks.
 ====
 
 * Do not use `meta: end_play`.
@@ -209,7 +209,38 @@ Rationale:: It aborts the whole play instead of a given host (with multiple host
 If absolutely necessary, consider using `meta: end_host`.
 ====
 
-* Task names can be made dynamic by using variables (wrapped in Jinja2 templates), this helps with reading the logs.
+* Task names can be made dynamic by using variables wrapped in Jinja2 templates at the end of the string
++
+[%collapsible]
+====
+Rationale:: This can help with reading the logs.
+For example, if the task is managing one of several devices, and you want the task name output to show the device being managed.
+However, the template must come at the *end* of the string - see (https://ansible-lint.readthedocs.io/rules/name/[Ansible Lint name template rule]).
+Note that in some cases, it can make it harder for users to correlate the logs to the code.
+For example, if there is a log message like "Manage the disk device /dev/dsk/0001", and the user tries to do something like `grep "Manage the disk device /dev/dsk/0001" rolename/tasks/*.yml` to figure out which task this comes from, they will not find it.
+If the template comes at the end of the string, the user will know to omit the device name from `grep`.
+A better way to debug is to use `ansible-playbook -vv`, which will show the exact file and line number of the task.
+
+Example::
+.Do this:
+[source,yaml]
+----
+tasks:
+  - name: Manage the disk device {{ storage_device_name }}
+    some.module:
+      device: "{{ storage_device_name }}"
+----
+
+.Don't do this:
+[source,yaml]
+----
+tasks:
+  - name: Manage {{ storage_device_name }}, the disk device
+    some.module:
+      device: "{{ storage_device_name }}"
+----
+====
+
 * Do not use variables (wrapped in Jinja2 templates) for play names; variables don't get expanded properly there.
   The same applies to loop variables (by default `item`) in task names within a loop.
   They, too, don't get properly expanded and hence are not to be used there.
@@ -334,7 +365,7 @@ Grouping sets of similar files into a subdirectory of `templates` is allowable,
   In many cases, if the platform is different, the package name is also different so that using `package` doesn't help a lot.
   Prefer then the more specific `yum`, `dnf` or `apt` module if you anyway need to differentiate.
 
-* Use `float`, `int`, and `bool` filters to "cast" public API variables used in numeric operations in Jinja templates
+* Use `float`, `int`, and `bool` filters to "cast" public API variables to ensure type safety, especially for numeric operations in Jinja.
 +
 [%collapsible]
 ====