Docs: lint profiles (#2666)

* issue #2663 lint profile docs

* remove lint from heading

* update with cidrblock suggestion

Co-authored-by: Bradley A. Thornton <18386516+cidrblock@users.noreply.github.com>

* profile descriptions

Co-authored-by: Bradley A. Thornton <18386516+cidrblock@users.noreply.github.com>

* chore: auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

Co-authored-by: Bradley A. Thornton <18386516+cidrblock@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Sorin Sbarnea <ssbarnea@redhat.com>

docs/index.md

@@ -38,7 +38,7 @@ Philosophy<philosophy>
 installing
 usage
 configuring
-profiles
+using-profiles
 rules
 ```
 

docs/using-profiles.md

@@ -0,0 +1,44 @@
+(using-lint-profiles)=
+
+# Applying profiles
+
+Ansible-lint profiles allow content creators to progressively improve the quality of Ansible playbooks, roles, and collections.
+
+During early development cycles, you need Ansible-lint rules to be less strict.
+Starting with the minimal profile ensures that Ansible can load your content.
+As you move to the next stage of developing content, you can gradually apply profiles to avoid common pitfalls and brittle complexity.
+Then, when you are ready to publish or share your content, you can use the `shared` and `production` profiles with much stricter rules.
+These profiles harden security, guarantee reliability, and ensure your Ansible content is easy for others to contribute to and use.
+
+```{note}
+Tags such as `opt-in` and `experimental` do not take effect for rules that are included in profiles, directly or indirectly.
+If a rule is in a profile, Ansible-lint applies that rule to the content.
+```
+
+After you install and configure `ansible-lint`, you can apply profiles as follows:
+
+1. View available profiles with the `-P` flag.
+
+   ```bash
+   ansible-lint -P
+   ```
+
+2. Specify a profile with the `--profile` parameter to lint your content with those rules, for example:
+
+- Enforce standard styles and formatting with the `basic` profile.
+
+  ```bash
+  ansible-lint --profile=basic
+  ```
+
+- Ensure automation consistency, reliability, and security with the `safety` profile.
+
+  ```bash
+  ansible-lint --profile=safety
+  ```
+
+```{toctree}
+:maxdepth: 1
+
+profiles
+```

src/ansiblelint/data/profiles.yml

@@ -3,10 +3,10 @@
 # progressive the profiles are, each one extending the one before it.
 min:
   description: >
-    Ensures that Ansible would be able to load that content, nothing else.
-    None of the rules can be disabled as they are considered fatal errors. You
-    can still add files to exclude list or add missing dependencies, so the
-    right files can be loaded.
+    The `min` profile ensures that Ansible can load content.
+    Rules in this profile are mandatory because they prevent fatal errors.
+    You can add files to the exclude list or provide dependencies to load the
+    correct files.
   extends: null
   rules:
     internal-error:
@@ -15,9 +15,7 @@ min:
     syntax-check:
 basic:
   description: >
-    Basic profile enables a set of rules designed to spot very common coding
-    mistakes, deprecations and require user to follow standardized style and
-    formatting.
+    The `basic` profile prevents common coding issues and enforces standard styles and formatting.
   extends: min
   rules:
     command-instead-of-module:
@@ -44,9 +42,7 @@ basic:
     - name[casing]
 moderate:
   description: >
-    The moderate profile is raising the bar a little bit by requiring you to
-    follow few other proven good practices that make the content easier to read
-    and maintain.
+    The `moderate` profile ensures that content adheres to best practices for making content easier to read and maintain.
   extends: basic
   rules:
     name[template]:
@@ -59,8 +55,7 @@ moderate:
       url: https://github.com/ansible/ansible-lint/issues/2168
 safety:
   description: >
-    The safety profile require user to avoid risky module calls that can have
-    a non-determinant outcomes and cause security issues in some cases.
+    The `safety` profile avoids module calls that can have non-determinant outcomes or security concerns.
   extends: moderate
   rules:
     avoid-implicit:
@@ -72,13 +67,12 @@ safety:
 shared:
   extends: safety
   description: >
-    The shared profile is for those that want to publish their content, roles
-    or collection to either [galaxy.ansible.com](https://galaxy.ansible.com),
-    [automation-hub](https://console.redhat.com/ansible/automation-hub) or
-    another private instance of these. In addition to all the rules related to
-    packaging and publishing, like metadata checks, this also includes some
-    rules that are known to be good practices for keeping the code readable and
-    maintainable.
+    The `shared` profile ensures that content follows best practices for packaging and publishing.
+    This profile is intended for content creators who want to make Ansible
+    playbooks, roles, or collections available from
+    [galaxy.ansible.com](https://galaxy.ansible.com),
+    [automation-hub](https://console.redhat.com/ansible/automation-hub),
+    or a private instance.
   rules:
     galaxy: # <-- applies to both galaxy and automation-hub
     ignore-errors:
@@ -107,9 +101,9 @@ shared:
       url: https://github.com/ansible/ansible-lint/issues/2038
 production:
   description: >
-    The production profile represents the top level of verification and it
-    is required for inclusion in [Ansible Automation Platform (AAP)](https://www.redhat.com/en/technologies/management/ansible)
-    as either validated or certified content.
+    The `production` profile ensures that content meets requirements for
+    inclusion in [Ansible Automation Platform (AAP)](https://www.redhat.com/en/technologies/management/ansible)
+    as validated or certified content.
   extends: shared
   rules:
     avoid-dot-notation:

src/ansiblelint/generate_docs.py

@@ -132,22 +132,10 @@ def profiles_as_md(header: bool = False, docs_url: str = RULE_DOC_URL) -> str:
 -->
 # Profiles
 
-One of the best ways to run `ansible-lint` is by specifying which rule profile
-you want to use. These profiles stack on top of each other, allowing you to
-gradually raise the quality bar.
-
-To run it with the most strict profile just type `ansible-lint --profile=production`.
-
-If you want to consult the list of rules from each profile, type
-`ansible-lint -P`. For your convenience, we also list the same output below.
-
-The rules that have a `*` suffix, are not implemented yet but we documented
-them with links to their issues.
+Ansible-lint profiles gradually increase the strictness of rules as your Ansible content lifecycle.
 
 ```{note}
-Special rule tags such `opt-in` and `experimental` are automatically removed
-when a rule is included in a profile, directly or indirectly. This means that
-they will always execute once included.
+Rules with `*` in the suffix are not yet implemented but are documented with linked GitHub issues.
 ```
 
 """