9 files changed, 109 insertions, 32 deletions
diff --git a/docs/_autofix_rules.md b/docs/_autofix_rules.md
new file mode 100644
index 0000000..15de3bb
--- /dev/null
+++ b/docs/_autofix_rules.md
@@ -0,0 +1,11 @@
+- [command-instead-of-shell](rules/command-instead-of-shell.md)
+- [deprecated-local-action](rules/deprecated-local-action.md)
+- [fqcn](rules/fqcn.md)
+- [jinja](rules/jinja.md)
+- [key-order](rules/key-order.md)
+- [name](rules/name.md)
+- [no-free-form](rules/no-free-form.md)
+- [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)
diff --git a/docs/autofix.md b/docs/autofix.md
new file mode 100644
index 0000000..8daef8d
--- /dev/null
+++ b/docs/autofix.md
@@ -0,0 +1,11 @@
+# Autofix
+
+Ansible-lint autofix can fix or simplify fixing issues identified by that rule. `ansible-lint --fix` will reformat YAML files and run transform for the given
+rules. You can limit the effective rule transforms (the 'write_list') by passing
+a keywords 'all' or 'none' or a comma separated list of rule ids or rule tags.
+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.
+
+Following is the list of supported rules covered under autofix functionality.
+
+{!_autofix_rules.md!}
diff --git a/docs/configuring.md b/docs/configuring.md
index e67bbbc..f61f1f7 100644
--- a/docs/configuring.md
+++ b/docs/configuring.md
@@ -5,10 +5,10 @@ You can ignore certain rules, enable `opt-in` rules, and control various other
 settings.
 
 Ansible-lint loads configuration from a file in the current working directory or
-from a file that you specify in the command line. If you provide configuration
-on both via a config file and on the command line, list values are merged (for
-example `exclude_paths`) and **True** is preferred for boolean values like
-`quiet`.
+from a file that you specify in the command line.
+
+Any configuration option that is passed from the command line will override
+the one specified inside the configuration file.
 
 ## Using local configuration files
 
@@ -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/
diff --git a/docs/contributing.md b/docs/contributing.md
index 3e8e41d..fc7cd15 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -8,8 +8,13 @@ After [creating your fork on GitHub], you can do:
 ```shell-session
 $ git clone --recursive git@github.com:your-name/ansible-lint
 $ cd ansible-lint
+$ # Recommended: Initialize and activate a Python virtual environment
+$ pip install --upgrade pip
+$ pip install -e .[test]       # Install testing dependencies
+$ tox run -e lint,pkg,docs,py  # Ensure subset of tox tests work in clean checkout
 $ git checkout -b your-branch-name
 # DO SOME CODING HERE
+$ tox run -e lint,pkg,docs,py  # Ensure subset of tox tests work with your changes
 $ git add your new files
 $ git commit -v
 $ git push origin your-branch-name
@@ -31,8 +36,6 @@ released.
 Automated tests will be run against all PRs, to run checks locally before
 pushing commits, just use [tox](https://tox.wiki/en/latest/).
 
-% DO-NOT-REMOVE-deps-snippet-PLACEHOLDER
-
 ## Talk to us
 
 Use Github [discussions] forum or for a live chat experience try
diff --git a/docs/installing.md b/docs/installing.md
index 6008de7..d8d6586 100644
--- a/docs/installing.md
+++ b/docs/installing.md
@@ -1,3 +1,8 @@
+---
+# YAML header
+render_macros: true
+---
+
 # Installing
 
 Install Ansible-lint to apply rules and follow best practices with your
@@ -13,9 +18,9 @@ automation content.
     this document. Before raising any bugs related to installation, review all of
     the following details:
 
-    - You should use installation methods outlined in this document only.
+    - You should use the installation methods outlined in this document only.
     - You should upgrade the Python installer (`pip` or `pipx`) to the latest
-      version available from pypi.org. If you used a system package manager, you
+      version available from pypi.org. If you use a system package manager, you
       will need to upgrade the installer to a newer version.
     - If you are installing from a git zip archive, which is not supported but
       should work, ensure you use the main branch and the latest version of pip and
@@ -27,20 +32,23 @@ automation content.
       [discussion](https://github.com/ansible/ansible-lint/discussions/2820#discussioncomment-4400380).
 
     Pull requests to improve installation instructions are welcome. Any new issues
-    related to installation will be closed and locked.
+    related to the installation will be closed and locked.
 
 For a container image, we recommend using
-[creator-ee](https://github.com/ansible/creator-ee/), which includes
-Ansible-lint. If you have a use case that the `creator-ee` container doesn't
-satisfy, please contact the team through the
-[discussions](https://github.com/ansible/ansible-lint/discussions) forum.
+[creator-ee](https://github.com/ansible/creator-ee/) which includes
+`ansible-dev-tools` (it combines critical Ansible development packages into a
+unified Python package). If you have a use case that the `creator-ee` container
+doesn't satisfy, please contact the team through the
+[discussion](https://github.com/ansible/ansible-lint/discussions) forum.
 
 You can also run Ansible-lint on your source code with the
-[Ansible-lint GitHub action](https://github.com/marketplace/actions/ansible-lint)
+[Ansible-lint GitHub action](https://github.com/marketplace/actions/run-ansible-lint)
 instead of installing it directly.
 
 ## Installing the latest version
 
+{{ install_from_adt("ansible-lint") }}
+
 You can install the most recent version of Ansible-lint with the [pip3] or
 [pipx] Python package manager. Use [pipx] to isolate Ansible-lint from your
 current Python environment as an alternative to creating a virtual environment.
@@ -50,6 +58,16 @@ current Python environment as an alternative to creating a virtual environment.
 pip3 install ansible-lint
 ```
 
+!!! note
+
+    If you want to install the exact versions of all dependencies that were used to
+    test a specific version of ansible-lint, you can add `lock` extra. This will
+    only work with Python 3.10 or newer. Do this only inside a virtual environment.
+
+    ```bash
+    pip3 install "ansible-lint[lock]"
+    ```
+
 ## Installing on Fedora and RHEL
 
 You can install Ansible-lint on Fedora, or Red Hat Enterprise Linux (RHEL) with
@@ -95,16 +113,17 @@ jobs:
     name: Ansible Lint # Naming the build is important to use it as a status check
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@v4
       - name: Run ansible-lint
         uses: ansible/ansible-lint@v6
 ```
 
 Due to limitations on how GitHub Actions are processing arguments, we do not
 plan to provide extra options. You will have to make use of
-[ansible-lint own configuration file](https://ansible-lint.readthedocs.io/configuring/)
-for altering its behavior.
+[ansible-lint own configuration file](https://ansible.readthedocs.io/projects/lint/configuring/)
+to alter its behavior.
 
-To also enable [dependabot][dependabot] automatic updates the newer versions of
+To also enable [dependabot][dependabot] automatic updates, the newer versions of
 ansible-lint action you should create a file similar to
 [.github/dependabot.yml][.github/dependabot.yml]
 
diff --git a/docs/philosophy.md b/docs/philosophy.md
index 2ef698d..da85bba 100644
--- a/docs/philosophy.md
+++ b/docs/philosophy.md
@@ -93,7 +93,7 @@ only when a major version is released.
 Not really. The certification process is likely to use only a subset of rules.
 At this time, we are working on building that list.
 
-### Why lots of official Ansible docs examples are not passing linting?
+### Why do many official Ansible docs examples fail to pass linting?
 
 Most of the official examples are written to exemplify specific features, and
 some might conflict with our rules. Still, we plan to include linting of
diff --git a/docs/rules/complexity.md b/docs/rules/complexity.md
new file mode 120000
index 0000000..6ab4e69
--- /dev/null
+++ b/docs/rules/complexity.md
@@ -0,0 +1 @@
+../../src/ansiblelint/rules/complexity.md
+\ No newline at end of file
diff --git a/docs/rules/index.md b/docs/rules/index.md
index 4f4dc3d..43ac967 100644
--- a/docs/rules/index.md
+++ b/docs/rules/index.md
@@ -2,6 +2,7 @@
 
 - [args][]
 - [avoid-implicit][]
+- [complexity][]
 - [command-instead-of-module][]
 - [command-instead-of-shell][]
 - [deprecated-bare-vars][]
diff --git a/docs/usage.md b/docs/usage.md
index dbe115d..da059a1 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -43,11 +43,11 @@ repositories.
 ## Gradual adoption
 
 For an easier gradual adoption, adopters should consider [ignore
-file][configuring.md#ignoring-rules-for-entire-files] feature. This allows the
-quick introduction of a linter pipeline for preventing addition of new
-violations, while known violations are ignored. Some people can work on
-addressing these historical violations while others may continue to work on
-other maintenance tasks.
+file][ignoring-rules-for-entire-files] feature. This allows the quick
+introduction of a linter pipeline for preventing the addition of new violations,
+while known violations are ignored. Some people can work on addressing these
+historical violations while others may continue to work on other maintenance
+tasks.
 
 The deprecated `--progressive` mode was removed in v6.16.0 as it added code
 complexity and performance overhead. It also presented several corner cases
@@ -124,7 +124,7 @@ ansible-lint --offline -q -f codeclimate examples/playbooks/norole.yml
 ```
 
 Historically `-f json` was used to generate Code Climate JSON reports but in
-never versions we switched its meaning point SARIF JSON format instead.
+newer versions we switched its meaning point SARIF JSON format instead.
 
 !!! warning
 
@@ -222,18 +222,12 @@ argument or add it to `skip_list` in your configuration.
 
 The least preferred method of skipping rules is to skip all task-based rules for
 a task, which does not skip line-based rules. You can use the
-`skip_ansible_lint` tag with all tasks or the `warn` parameter with the
-_command_ or _shell_ modules, for example:
+`skip_ansible_lint` tag with all tasks, for example:
 
 ```yaml
 - name: This would typically fire no-free-form
   command: warn=no chmod 644 X
 
-- name: This would typically fire command-instead-of-module
-  command: git pull --rebase
-  args:
-    warn: false
-
 - name: This would typically fire git-latest
   git: src=/path/to/git/repo dest=checkout
   tags: