Update the documentation of the modules (attributes) (#14)

* Updating the modules' documentation (attributes)

* Update parameter type in quay_notification

---------

Co-authored-by: Hervé Quatremain <herve.quatremain@redhat.com>

.pre-commit-config.yaml

@@ -20,7 +20,7 @@ repos:
         types:
           - yaml
   - repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 24.10.0
     hooks:
       - id: black
         name: black

plugins/modules/quay_api_token.py

@@ -77,7 +77,6 @@
     type: str
     required: false
 notes:
-  - Supports C(check_mode).
   - O(for_user) requires Quay version 3.12 or later.
   - Your Quay administrator must enable the OAuth assignment capability
     of your Quay installation (C(FEATURE_ASSIGN_OAUTH_TOKEN) in C(config.yaml))
@@ -90,7 +89,16 @@
   - The module is not idempotent. Every time you run it, an additional OAuth
     access token is produced. The other OAuth access tokens stay valid.
   - You cannot delete OAuth access tokens.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
 """
 

plugins/modules/quay_application.py

@@ -75,10 +75,18 @@
     default: present
     choices: [absent, present]
 notes:
-  - Supports C(check_mode).
   - The token that you provide in O(quay_token) must have the "Administer
     Organization" permission.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_default_perm.py

@@ -82,10 +82,18 @@
     default: present
     choices: [absent, present]
 notes:
-  - Supports C(check_mode).
   - The token that you provide in O(quay_token) must have the "Administer
     Organization" and "Administer User" permissions.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_docker_token.py

@@ -54,10 +54,18 @@
     default: present
     choices: [absent, present]
 notes:
-  - Supports C(check_mode).
   - The tokens you create with this module are unrelated to OAUth access tokens
     that you use to access the Quay API.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_first_user.py

@@ -80,8 +80,16 @@
     authentication (C(AUTHENTICATION_TYPE) to C(Database) in C(config.yaml)).
   - Use the module just after installing Quay, when the database is empty.
     The module fails if user accounts are already defined in the database.
-  - Supports C(check_mode).
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
 """
 
@@ -144,7 +152,11 @@ def main():
     password = module.params.get("password")
     create_token = module.params.get("create_token")
 
-    new_fields = {"username": username, "password": password, "access_token": create_token}
+    new_fields = {
+        "username": username,
+        "password": password,
+        "access_token": create_token,
+    }
     if email:
         new_fields["email"] = email
     data = module.create("user", username, "user/initialize", new_fields, auto_exit=False)

plugins/modules/quay_layer_info.py

@@ -40,7 +40,16 @@
       - If you omit the tag and the digest part, then C(latest) is assumed.
     required: true
     type: str
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_manifest_label.py

@@ -71,10 +71,18 @@
 notes:
   - Labels defined in the Containerfile/Dockerfile cannot be deleted or
     updated. They are read-only.
-  - Supports C(check_mode).
   - The user account associated with the token that you provide in
     O(quay_token) must have write access to the repository.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_manifest_label_info.py

@@ -46,7 +46,16 @@
       - Gather information on the labels with that specific key instead of
         returning data on all the labels in the manifest.
     type: str
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_message.py

@@ -94,10 +94,18 @@
     default: present
     choices: [absent, present]
 notes:
-  - Supports C(check_mode).
   - The token that you provide in O(quay_token) must have the
     "Super User Access" permission.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_notification.py

@@ -107,7 +107,7 @@
       template:
         description:
           - JSON data for the body content of the webhook POST method.
-        type: str
+        type: jsonarg
       room_id:
         description:
           - Chat room ID required for the HipChat notification method.
@@ -194,15 +194,23 @@
     default: present
     choices: [absent, present]
 notes:
-  - Supports C(check_mode).
   - Your Quay administrator must enable the image garbage collection capability
     of your Quay installation (C(FEATURE_GARBAGE_COLLECTION) in C(config.yaml))
     to use the V(repo_image_expiry) event.
   - Using the V(repo_image_expiry) event and the O(image_expiry_days) parameter
     requires Quay version 3.12 or later.
   - The user account associated with the token that you provide in
     O(quay_token) must have administrator access to the repository.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """
@@ -232,7 +240,7 @@
     method: webhook
     config:
       url: https://webhook.example.com/webhook/12345
-      template: "{{ lookup('file', 'post.json') | string }}"
+      template: "{{ lookup('ansible.builtin.file', 'post.json') }}"
     state: present
     quay_host: https://quay.example.com
     quay_token: vgfH9zH5q6eV16Con7SvDQYSr0KPYQimMHVehZv7
@@ -248,7 +256,7 @@
     method: webhook
     config:
       url: https://webhook.example.com/webhook/12345
-      template: "{{ lookup('file', 'post.json') | string }}"
+      template: "{{ lookup('ansible.builtin.file', 'post.json') }}"
     state: present
     quay_host: https://quay.example.com
     quay_token: vgfH9zH5q6eV16Con7SvDQYSr0KPYQimMHVehZv7
@@ -361,7 +369,7 @@ def main():
                 # Slack and webhook notification
                 url=dict(),
                 # webhook notification
-                template=dict(),
+                template=dict(type="jsonarg"),
                 # HipChat notification
                 room_id=dict(),
                 notification_token=dict(no_log=True),

plugins/modules/quay_organization.py

@@ -72,7 +72,6 @@
     default: present
     choices: [absent, present]
 notes:
-  - Supports C(check_mode).
   - Your Quay administrator must enable the auto-prune capability of your Quay
     installation (C(FEATURE_AUTO_PRUNE) in C(config.yaml)) to use the
     O(auto_prune_method) and O(auto_prune_value) parameters.
@@ -82,7 +81,16 @@
     Organization" and "Administer User" permissions.
   - To rename organizations, the token must also have the "Super User Access"
     permission.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
   - infra.quay_configuration.autoprune

plugins/modules/quay_proxy_cache.py

@@ -84,10 +84,18 @@
   - When you set O(state) to V(present), the module always reports a changed
     status, because it cannot retrieve the current password for the remote
     registry to compare it with the O(password) parameter.
-  - Supports C(check_mode).
   - The token that you provide in O(quay_token) must have the "Administer
     Organization" permission.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_quota.py

@@ -73,10 +73,18 @@
   - The module requires that your Quay administrator enables quota management
     for your installation (by setting C(FEATURE_QUOTA_MANAGEMENT) to C(True) in
     C(config.yaml)).
-  - Supports C(check_mode).
   - The token that you provide in O(quay_token) must have the "Administer
     Organization" and "Administer User" permissions.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """

plugins/modules/quay_repository.py

@@ -119,10 +119,18 @@
   - Your Quay administrator must enable the mirroring capability of your Quay
     installation (C(FEATURE_REPO_MIRROR) in C(config.yaml)) to use the
     O(repo_state) parameter.
-  - Supports C(check_mode).
   - The token that you provide in O(quay_token) must have the "Administer
     Repositories" and "Create Repositories" permissions.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
   - infra.quay_configuration.autoprune
@@ -466,7 +474,8 @@ def main():
         #
         # If no policy is defined, then the returned data is {"policies": []}
         prune_details = module.get_object_path(
-            "repository/{full_repo_name}/autoprunepolicy/", full_repo_name=full_repo_name
+            "repository/{full_repo_name}/autoprunepolicy/",
+            full_repo_name=full_repo_name,
         )
         try:
             policies = prune_details["policies"]

plugins/modules/quay_repository_mirror.py

@@ -122,10 +122,18 @@
     O(infra.quay_configuration.quay_repository#module:repo_state)
     parameter in the M(infra.quay_configuration.quay_repository) module).
     The configuration is preserved when you disable mirroring.
-  - Supports C(check_mode).
   - The user account associated with the token that you provide in
     O(quay_token) must have administrator access to the repository.
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: all
 extends_documentation_fragment:
+  - ansible.builtin.action_common_attributes
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
 """
@@ -350,7 +358,10 @@ def main():
     if is_enabled is not None:
         new_fields["is_enabled"] = is_enabled
     if image_tags is not None:
-        new_fields["root_rule"] = {"rule_kind": "tag_glob_csv", "rule_value": image_tags}
+        new_fields["root_rule"] = {
+            "rule_kind": "tag_glob_csv",
+            "rule_value": image_tags,
+        }
 
     try:
         registry_config = copy.deepcopy(mirror_details["external_registry_config"])