Document pre-commit access to ansible community bundle (#3856)

Author: ssbarnea

.config/dictionary.txt

@@ -292,6 +292,7 @@ pyupgrade
 pyyaml
 redirections
 reexec
+reformatter
 regexes
 releasenotes
 relpath

docs/_autofix_rules.md

@@ -8,3 +8,4 @@
 - [no-jinja-when](rules/no-jinja-when.md)
 - [no-log-password](rules/no-log-password.md)
 - [partial-become](rules/partial-become.md)
+- [yaml](rules/yaml.md)

docs/configuring.md

@@ -57,17 +57,54 @@ Keep in mind that this will override any existing file content.
 
 ## Pre-commit setup
 
-To use Ansible-lint with [pre-commit], add the following to the
+To use Ansible-lint with the [pre-commit] tool, add the following to the
 `.pre-commit-config.yaml` file in your local repository.
 
+Do not confuse the [pre-commit] tool with the git hook feature that has the same name.
+While the [pre-commit] tool can also make use of git hooks, it does not require
+them and it does not install them by default.
+
+[pre-commit.ci] is a hosted service that can run pre-commit for you
+on each change but you can also run the tool yourself using the CI of your choice.
+
 Change **rev:** to either a commit sha or tag of Ansible-lint that contains
 `.pre-commit-hooks.yaml`.
 
 ```yaml
+---
+ci:
+  # This section is specific to pre-commit.ci, telling it to create a pull request
+  # to update the linter version tag every month.
+  autoupdate_schedule: monthly
+  # If you have other Ansible collection dependencies (requirements.yml)
+  # `pre-commit.ci` will not be able to install them because it runs in offline mode,
+  # and you will need to tell it to skip the hook.
+  # skip:
+  #   - ansible-lint
+repos:
 - repo: https://github.com/ansible/ansible-lint
   rev: ... # put latest release tag from https://github.com/ansible/ansible-lint/releases/
   hooks:
     - id: ansible-lint
+      # Uncomment if you need the full Ansible community bundle instead of ansible-core:
+      # additional_dependencies:
+      #   - ansible
 ```
 
+!!! warning
+
+    [pre-commit] always uses python virtual environments. If you happen to
+    use the [Ansible package] instead of just [ansible-core] you might be surprised
+    to see that pre-commit is not able to find these collections, even if
+    your local Ansible does. This is because they are installed inside a location
+    that is not available to the virtual environment in which pre-commit hook
+    is installed. In this case, you might want to uncomment the commented lines
+    from the hook definition above, so the bundle will be installed.
+
+    You should note that collection installed into `~/.ansible` are found by
+    the hook.
+
 [pre-commit]: https://pre-commit.com/
+[Ansible package]: https://pypi.org/project/ansible/
+[ansible-core]: https://pypi.org/project/ansible-core/
+[pre-commit.ci]: https://pre-commit.ci/

src/ansiblelint/rules/yaml.md

@@ -1,6 +1,24 @@
 # yaml
 
-This rule checks YAML syntax and is an implementation of `yamllint`.
+This rule checks YAML syntax by using [yamllint] but with few minor default
+configuration changes.
+
+!!! warning
+
+    [Auto-fix](../autofix.md) functionality will change **inline comment indentation to one
+    character instead of two**, which is the default of [yamllint]. The reason
+    for this decision is for keeping reformatting compatibility
+    with [prettier], which is the most popular reformatter.
+
+    ```yaml title=".yamllint"
+    rules:
+      comments:
+        min-spaces-from-content: 1 # prettier compatibility
+    ```
+
+    There is no need to create this yamllint config file, but if you also
+    run yamllint yourself, you might want to create it to make it behave
+    the same way as ansible-lint.
 
 You can disable YAML syntax violations by adding `yaml` to the `skip_list` in
 your Ansible-lint configuration as follows:
@@ -102,3 +120,5 @@ bar: ... # Correct comment indentation.
 [1.2.2]: https://yaml.org/spec/1.2.2/
 [yaml specification]: https://yaml.org/
 [guide]: https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics
+[prettier]: https://prettier.io/
+[yamllint]: https://yamllint.readthedocs.io/en/stable/

src/ansiblelint/rules/yaml_rule.py

@@ -3,14 +3,14 @@
 
 import logging
 import sys
-from collections.abc import Iterable
+from collections.abc import Iterable, MutableMapping, MutableSequence
 from typing import TYPE_CHECKING
 
 from yamllint.linter import run as run_yamllint
 
 from ansiblelint.constants import LINE_NUMBER_KEY, SKIPPED_RULES_KEY
 from ansiblelint.file_utils import Lintable
-from ansiblelint.rules import AnsibleLintRule
+from ansiblelint.rules import AnsibleLintRule, TransformMixin
 from ansiblelint.yaml_utils import load_yamllint_config
 
 if TYPE_CHECKING:
@@ -22,7 +22,7 @@
 _logger = logging.getLogger(__name__)
 
 
-class YamllintRule(AnsibleLintRule):
+class YamllintRule(AnsibleLintRule, TransformMixin):
     """Violations reported by yamllint."""
 
     id = "yaml"
@@ -92,6 +92,22 @@ def matchyaml(self, file: Lintable) -> list[MatchError]:
             )
         return matches
 
+    def transform(
+        self: YamllintRule,
+        match: MatchError,
+        lintable: Lintable,
+        data: MutableMapping[str, Any] | MutableSequence[Any] | str,
+    ) -> None:
+        """Transform yaml.
+
+        :param match: MatchError instance
+        :param lintable: Lintable instance
+        :param data: data to transform
+        """
+        # This method does nothing because the YAML reformatting is implemented
+        # in data dumper. Still presence of this method helps us with
+        # documentation generation.
+
 
 def _combine_skip_rules(data: Any) -> set[str]:
     """Return a consolidated list of skipped rules."""

tools/generate_docs.py

@@ -1,4 +1,4 @@
-#!/bin/env python3
+#!python3
 """Script that tests rule markdown documentation."""
 from __future__ import annotations