Document autofix ability for rules that supports it (#3791)

Author: ssbarnea

mkdocs.yml

@@ -115,7 +115,7 @@ plugins:
   - markdown-exec
   - gen-files:
       scripts:
-        - src/ansiblelint/generate_docs.py
+        - tools/generate_docs.py
   - material/search:
       separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
   - material/social

src/ansiblelint/generate_docs.py

@@ -58,6 +58,12 @@ def rules_as_md(rules: RulesCollection) -> str:
 
             result += f"\n\n## {title}\n\n**{rule.shortdesc}**\n\n{description}"
 
+        # Safety net for preventing us from adding autofix to rules and
+        # forgetting to mention it inside their documentation.
+        if "autofix" in rule.tags and "autofix" not in rule.description:
+            msg = f"Rule {rule.id} is invalid because it has 'autofix' tag but this ability is not documented in its description."
+            raise RuntimeError(msg)
+
     return result
 
 

src/ansiblelint/rules/command_instead_of_shell.md

@@ -29,64 +29,6 @@ environment variable expansion or chaining multiple commands using pipes.
       changed_when: false
 ```
 
-## Auto-fixing capability
+!!! note
 
-### Before autofix
-
-```yaml
----
-- name: Fixture
-  hosts: localhost
-  tasks:
-    - name: Shell no pipe
-      ansible.builtin.shell:
-        cmd: echo hello
-      changed_when: false
-
-    - name: Shell with jinja filter
-      ansible.builtin.shell:
-        cmd: echo {{ "hello" | upper }}
-      changed_when: false
-
-    - name: Shell with jinja filter (fqcn)
-      ansible.builtin.shell:
-        cmd: echo {{ "hello" | upper }}
-      changed_when: false
-
-    - name: Command with executable parameter
-      ansible.builtin.shell:
-        cmd: clear
-      args:
-        executable: /bin/bash
-      changed_when: false
-```
-
-### After autofix
-
-```yaml
----
-- name: Fixture
-  hosts: localhost
-  tasks:
-    - name: Shell no pipe
-      ansible.builtin.command:
-        cmd: echo hello
-      changed_when: false
-
-    - name: Shell with jinja filter
-      ansible.builtin.command:
-        cmd: echo {{ "hello" | upper }}
-      changed_when: false
-
-    - name: Shell with jinja filter (fqcn)
-      ansible.builtin.command:
-        cmd: echo {{ "hello" | upper }}
-      changed_when: false
-
-    - name: Command with executable parameter
-      ansible.builtin.shell:
-        cmd: clear
-      args:
-        executable: /bin/bash
-      changed_when: false
-```
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/deprecated_local_action.md

@@ -19,3 +19,7 @@ This rule recommends using `delegate_to: localhost` instead of the
     ansible.builtin.debug:
   delegate_to: localhost # <-- recommended way to run on localhost
 ```
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/fqcn.md

@@ -87,3 +87,7 @@ structure in a backward-compatible way by adding redirects like in
       # Use the FQCN for the builtin shell module.
       ansible.builtin.shell: ssh ssh_user@{{ ansible_ssh_host }}
 ```
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/jinja.md

@@ -53,3 +53,7 @@ In its current form, this rule presents the following limitations:
   does not support tilde as a binary operator. Example: `{{ a ~ b }}`.
 - Jinja2 blocks that use dot notation with numbers are ignored because python
   and black do not allow it. Example: `{{ foo.0.bar }}`
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/key_order.md

@@ -61,3 +61,7 @@ we concluded that the block keys must be the last ones.
 
 Another common practice was to put `tags` as the last property. Still, for the
 same reasons, we decided that they should not be put after block keys either.
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/name.md

@@ -59,3 +59,7 @@ your `enable_list` to activate it.
     - name: Create placeholder file
       ansible.builtin.command: touch /tmp/.placeholder
 ```
+
+!!! note
+
+    `name[casing]` can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/no_free_form.md

@@ -56,3 +56,7 @@ This rule can produce messages as:
         executable: /bin/bash # <-- explicit is better
       changed_when: false
 ```
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/no_jinja_when.md

@@ -30,3 +30,7 @@ anti-pattern and does not produce expected results.
       ansible.builtin.command: /sbin/shutdown -t now
       when: ansible_facts['os_family'] == "Debian" # <- Uses facts in a conditional statement.
 ```
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/no_log_password.md

@@ -43,3 +43,7 @@ Explicitly adding `no_log: true` prevents accidentally exposing secrets.
         - wow
       no_log: true # <- Sets the no_log attribute to a non-false value.
 ```
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

src/ansiblelint/rules/partial_become.md

@@ -120,3 +120,7 @@ This rule can produce the following messages:
   become: true # <- Activates privilege escalation.
   become_user: apache # <- Does not change the user because "become: true" is not set.
 ```
+
+!!! note
+
+    This rule can be automatically fixed using [`--fix`](/autofix) option.

tools/generate_docs.py

@@ -0,0 +1,10 @@
+#!/bin/env python3
+"""Script that tests rule markdown documentation."""
+import subprocess
+
+subprocess.run(
+    "ansible-lint -L --format=md",  # noqa: S607
+    shell=True,  # noqa: S602
+    check=True,
+    stdout=subprocess.DEVNULL,
+)