Fix lint config

Closes #4

.ansible-lint

@@ -1,4 +1,5 @@
 ---
+###
 # ```{rubric} .ansible-lint
 # ```
 # ---
@@ -7,21 +8,40 @@
 #
 # Ansible-lint does not automatically load rules that have the 'opt-in' tag.
 # You must enable opt-in rules by listing each rule 'id' below.
+#
+# add yaml here if you want to avoid ignoring yaml checks when yamllint
+# library is missing. Normally its absence just skips using that rule.
+#
+# ```{literalinclude} /.ansible-lint
+# :language: yaml
+# :start-at: "enable_list:\n"
+# :end-before: "###\n"
+# ```
 enable_list:
   - args
   - empty-string-compare # opt-in
   - no-log-password # opt-in
   - no-same-owner # opt-in
   - name[prefix] # opt-in
-  # add yaml here if you want to avoid ignoring yaml checks when yamllint
-  # library is missing. Normally its absence just skips using that rule.
   - yaml
+###
+# ```{rubric} Exclude Paths
+# ```
+# ---
 # Report only a subset of tags and fully ignore any others
 # tags:
 #   - jinja[spacing]
-# exclude_paths included in this file are parsed relative to this file's location
-# and not relative to the CWD of execution. CLI arguments passed to the --exclude
+#
+# `exclude_paths` included in this file are parsed relative to this file's
+# location
+# and not relative to the CWD of execution. CLI arguments passed to the
+# `--exclude`
 # option are parsed relative to the CWD of execution.
+#
+# ```{literalinclude} /.ansible-lint
+# :start-at: "exclude_paths:\n"
+# :end-before: "###\n"
+# ```
 exclude_paths:
   - .cache/ # implicit unless exclude_paths is defined in config
   - test/fixtures/formatting-before/
@@ -30,44 +50,73 @@ exclude_paths:
   - _static/
   - .markdownlint-cli2.yaml
   - .markdownlint.yaml
+###
+# ```{rubric} Kinds
+# ```
+# ---
 # parseable: true
 # quiet: true
 # strict: true
 # verbosity: 1
 # List of additional kind:pattern to be added at the top of the default
 # match list, first match determines the file kind.
+#
+# ```{literalinclude} /.ansible-lint
+# :start-at: "kinds:\n"
+# :end-before: "###\n"
+# ```
 kinds:
   # - playbook: "**/examples/*.{yml,yaml}"
   # - galaxy: "**/folder/galaxy.yml"
   # - tasks: "**/tasks/*.yml"
   # - vars: "**/vars/*.yml"
   # - meta: "**/meta/main.yml"
   - playbook: "site.yaml"
-
+###
 # Enable checking of loop variable prefixes in roles
 loop_var_prefix: "^(__|{role}_)"
+###
+# ```{rubric} Mocks
+# ```
+# ---
 # Mock modules or roles in order to pass ansible-playbook --syntax-check
+#
+# note the foo.bar is invalid as being neither a module or a collection
+#
+# ```{literalinclude} /.ansible-lint
+# :start-at: "mock_modules:\n"
+# :end-before: "###\n"
+# ```
 mock_modules:
   - zuul_return
-  # note the foo.bar is invalid as being neither a module or a collection
   - fake_namespace.fake_collection.fake_module
   - fake_namespace.fake_collection.fake_module.fake_submodule
+###
+# role within a collection
+# old standalone galaxy role
+#
+# ```{literalinclude} /.ansible-lint
+# :start-at: "mock_roles:\n"
+# :end-before: "###\n"
+# ```
 mock_roles:
   - mocked_role
-  - author.role_name # old standalone galaxy role
-  - fake_namespace.fake_collection.fake_role # role within a collection
+  - author.role_name
+  - fake_namespace.fake_collection.fake_role
+###
 # Some rules can transform files to fix (or make it easier to fix) identified
 # errors. `ansible-lint --fix` will reformat YAML files and run these transforms.
 # By default it will run all transforms (effectively `write_list: ["all"]`).
 # You can disable running transforms by setting `write_list: ["none"]`.
 # Or only enable a subset of rule transforms by listing rules/tags here.
 # write_list:
 #   - all
-
 # Offline mode disables installation of requirements.yml and schema refreshing
 offline: true
-
-profile: null # min, basic, moderate,safety, shared, production
+###
+# min, basic, moderate,safety, shared, production
+profile: null
+###
 # Ansible-lint is able to recognize and load skip rules stored inside
 # `.ansible-lint-ignore` (or `.config/ansible-lint-ignore.txt`) files.
 # To skip a rule just enter filename and tag, like "playbook.yml package-latest"
@@ -76,52 +125,57 @@ profile: null # min, basic, moderate,safety, shared, production
 # the use of skip_list below because that will hide violations from the output.
 # When putting ignores inside the ignore file, they are marked as ignored, but
 # still visible, making it easier to address later.
+#
+# ```{literalinclude} /.ansible-lint
+# :start-at: "skip_list:\n"
+# :end-before: "###\n"
+# ```
 skip_list:
   - skip_this_tag
-
-
-
-
-
-
-
+###
 # Define required Ansible's variables to satisfy syntax check
 # extra_vars:
 #   secret_ca_passphrase: foobar
 # multiline_string_variable: |
 #   line1
 #   line2
 # complex_variable: ":{;\t$()"
-
+#
 # Uncomment to enforce action validation with tasks, usually is not
 # needed as Ansible syntax check also covers it.
 # skip_action_validation: false
-
-
+#
 # List of additional collections to allow in only-builtins rule.
 # only_builtins_allow_collections:
 #   - example_ns.example_collection
-
+#
 # only_builtins_allow_modules:
 # List of additions modules to allow in only-builtins rule.
 #   - example_module
-
+#
 # Allow setting custom prefix for name[prefix] rule
 task_name_prefix: "{stem} | "
-use_default_rules: true
+###
 # Load custom rules from this specific folder
 # rulesdir:
 #   - ./rule/directory/
+use_default_rules: true
+###
 # Complexity related settings
-
 # Limit the depth of the nested blocks:
 # max_block_depth: 20
 # Enforce variable names to follow pattern below, in addition to Ansible own
 # requirements, like avoiding python identifiers. To disable add `var-naming`
 # to skip_list.
 var_naming_pattern: "^[a-z_][a-z0-9_]*$"
-
+###
+# ```{rubric} Warn List
+# ```
+# ---
 # Ansible-lint does not fail on warnings from the rules or tags listed below
+# ```{literalinclude} /.ansible-lint
+# :start-at: "skip_list:\n"
+# ```
 warn_list:
   - skip_this_tag
   - experimental # experimental is included in the implicit list

cicd.md

@@ -39,3 +39,12 @@ And ShellCheck never hurt anybody either.
 
 ```{autoyaml} .github/workflows/shell.yml
 ```
+
+## Lint
+
+This is the configuration for the various lint tools used here.
+
+### ansible-lint
+
+```{autoyaml} .ansible-lint
+```