From 411f6a1feb469322c69379289fd03c542cc3258c Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Thu, 3 Nov 2022 09:25:57 -0400
Subject: [PATCH 1/7] add action_group attribute

---
 plugins/doc_fragments/action_group.py         | 19 +++++++++++++++++++
 plugins/modules/vault_kv1_get.py              |  1 +
 plugins/modules/vault_kv2_delete.py           |  1 +
 plugins/modules/vault_kv2_get.py              |  1 +
 plugins/modules/vault_login.py                |  1 +
 .../modules/vault_pki_generate_certificate.py |  1 +
 plugins/modules/vault_read.py                 |  1 +
 plugins/modules/vault_token_create.py         |  1 +
 plugins/modules/vault_write.py                |  1 +
 9 files changed, 27 insertions(+)
 create mode 100644 plugins/doc_fragments/action_group.py

diff --git a/plugins/doc_fragments/action_group.py b/plugins/doc_fragments/action_group.py
new file mode 100644
index 000000000..0f3fa4c63
--- /dev/null
+++ b/plugins/doc_fragments/action_group.py
@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2022, Brian Scholer (@briantist)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    DOCUMENTATION = r'''
+options: {}
+attributes:
+  action_group:
+    membership:
+      - vault
+'''
diff --git a/plugins/modules/vault_kv1_get.py b/plugins/modules/vault_kv1_get.py
index 667a11378..0b69ae7dc 100644
--- a/plugins/modules/vault_kv1_get.py
+++ b/plugins/modules/vault_kv1_get.py
@@ -26,6 +26,7 @@
     description: Documentation for the Vault KV secrets engine, version 1.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v1
 extends_documentation_fragment:
+  - community.hashi_vault.action_group
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount
diff --git a/plugins/modules/vault_kv2_delete.py b/plugins/modules/vault_kv2_delete.py
index e215751f4..cd3e71264 100644
--- a/plugins/modules/vault_kv2_delete.py
+++ b/plugins/modules/vault_kv2_delete.py
@@ -29,6 +29,7 @@
     description: Documentation for the Vault KV secrets engine, version 2.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v2
 extends_documentation_fragment:
+  - community.hashi_vault.action_group
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount
diff --git a/plugins/modules/vault_kv2_get.py b/plugins/modules/vault_kv2_get.py
index 343da2658..0284efb07 100644
--- a/plugins/modules/vault_kv2_get.py
+++ b/plugins/modules/vault_kv2_get.py
@@ -26,6 +26,7 @@
     description: Documentation for the Vault KV secrets engine, version 2.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v2
 extends_documentation_fragment:
+  - community.hashi_vault.action_group
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount
diff --git a/plugins/modules/vault_login.py b/plugins/modules/vault_login.py
index 0cc411cec..c43c9124f 100644
--- a/plugins/modules/vault_login.py
+++ b/plugins/modules/vault_login.py
@@ -24,6 +24,7 @@
     - ref: community.hashi_vault.vault_login_token filter <ansible_collections.community.hashi_vault.vault_login_token_filter>
       description: The official documentation for the C(community.hashi_vault.vault_login_token) filter plugin.
   extends_documentation_fragment:
+    - community.hashi_vault.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
   notes:
diff --git a/plugins/modules/vault_pki_generate_certificate.py b/plugins/modules/vault_pki_generate_certificate.py
index ffa3d9038..0faabcf9c 100644
--- a/plugins/modules/vault_pki_generate_certificate.py
+++ b/plugins/modules/vault_pki_generate_certificate.py
@@ -26,6 +26,7 @@
       description: HVAC library reference about the PKI engine.
       link: https://hvac.readthedocs.io/en/stable/usage/secrets_engines/pki.html#generate-certificate
   extends_documentation_fragment:
+    - community.hashi_vault.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.engine_mount
diff --git a/plugins/modules/vault_read.py b/plugins/modules/vault_read.py
index 5bbda8dec..2aae6b2a9 100644
--- a/plugins/modules/vault_read.py
+++ b/plugins/modules/vault_read.py
@@ -24,6 +24,7 @@
     - ref: community.hashi_vault.hashi_vault lookup <ansible_collections.community.hashi_vault.hashi_vault_lookup>
       description: The official documentation for the C(community.hashi_vault.hashi_vault) lookup plugin.
   extends_documentation_fragment:
+    - community.hashi_vault.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
   options:
diff --git a/plugins/modules/vault_token_create.py b/plugins/modules/vault_token_create.py
index 4fd757b06..a8edcc2ff 100644
--- a/plugins/modules/vault_token_create.py
+++ b/plugins/modules/vault_token_create.py
@@ -27,6 +27,7 @@
     - ref: community.hashi_vault.vault_login_token filter <ansible_collections.community.hashi_vault.vault_login_token_filter>
       description: The official documentation for the C(community.hashi_vault.vault_login_token) filter plugin.
   extends_documentation_fragment:
+    - community.hashi_vault.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.token_create
diff --git a/plugins/modules/vault_write.py b/plugins/modules/vault_write.py
index e0833da94..a94349b36 100644
--- a/plugins/modules/vault_write.py
+++ b/plugins/modules/vault_write.py
@@ -30,6 +30,7 @@
     - ref: community.hashi_vault.vault_read lookup <ansible_collections.community.hashi_vault.vault_read_lookup>
       description: The official documentation for the C(community.hashi_vault.vault_read) lookup plugin.
   extends_documentation_fragment:
+    - community.hashi_vault.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.wrapping

From 19fd261964024d3bea71203abf37a906e5c90040 Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Thu, 3 Nov 2022 09:47:32 -0400
Subject: [PATCH 2/7] add missing fields

---
 plugins/doc_fragments/action_group.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/plugins/doc_fragments/action_group.py b/plugins/doc_fragments/action_group.py
index 0f3fa4c63..199440db8 100644
--- a/plugins/doc_fragments/action_group.py
+++ b/plugins/doc_fragments/action_group.py
@@ -14,6 +14,8 @@ class ModuleDocFragment(object):
 options: {}
 attributes:
   action_group:
+    description: Use C(group/community.hashi_vault.vault) in C(module_defaults) to set defaults for this module.
+    support: full
     membership:
       - vault
 '''

From 44053d3bfdbf3c994cf1e1acf2ede5031a2d669e Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Fri, 4 Nov 2022 16:45:44 -0400
Subject: [PATCH 3/7] Update plugins/doc_fragments/action_group.py

Co-authored-by: Felix Fontein <felix@fontein.de>
---
 plugins/doc_fragments/action_group.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/doc_fragments/action_group.py b/plugins/doc_fragments/action_group.py
index 199440db8..9a365c4e6 100644
--- a/plugins/doc_fragments/action_group.py
+++ b/plugins/doc_fragments/action_group.py
@@ -17,5 +17,5 @@ class ModuleDocFragment(object):
     description: Use C(group/community.hashi_vault.vault) in C(module_defaults) to set defaults for this module.
     support: full
     membership:
-      - vault
+      - community.hashi_vault.vault
 '''

From e50584a19dacb16532fb4c38c44d4079bfb09195 Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Fri, 4 Nov 2022 17:42:37 -0400
Subject: [PATCH 4/7] refactor

---
 .../doc_fragments/{action_group.py => attributes.py}   | 10 ++++++++++
 1 file changed, 10 insertions(+)
 rename plugins/doc_fragments/{action_group.py => attributes.py} (75%)

diff --git a/plugins/doc_fragments/action_group.py b/plugins/doc_fragments/attributes.py
similarity index 75%
rename from plugins/doc_fragments/action_group.py
rename to plugins/doc_fragments/attributes.py
index 9a365c4e6..2914c986e 100644
--- a/plugins/doc_fragments/action_group.py
+++ b/plugins/doc_fragments/attributes.py
@@ -12,6 +12,9 @@ class ModuleDocFragment(object):
 
     DOCUMENTATION = r'''
 options: {}
+'''
+
+    ACTION_GROUP = r'''
 attributes:
   action_group:
     description: Use C(group/community.hashi_vault.vault) in C(module_defaults) to set defaults for this module.
@@ -19,3 +22,10 @@ class ModuleDocFragment(object):
     membership:
       - community.hashi_vault.vault
 '''
+
+    CHECK_MODE_READ_ONLY = r'''
+attributes:
+  check_mode:
+    support: full
+    description: This module is "read only" and operates the same regardless of check mode.
+'''

From 378a128909b3b357682442d473726b3a97489ec7 Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Fri, 4 Nov 2022 17:42:47 -0400
Subject: [PATCH 5/7] update modules

---
 plugins/modules/vault_kv1_get.py                  |  3 ++-
 plugins/modules/vault_kv2_delete.py               | 10 +++++++---
 plugins/modules/vault_kv2_get.py                  |  3 ++-
 plugins/modules/vault_login.py                    | 12 ++++++++----
 plugins/modules/vault_pki_generate_certificate.py |  6 +++++-
 plugins/modules/vault_read.py                     |  3 ++-
 plugins/modules/vault_token_create.py             | 12 ++++++++----
 plugins/modules/vault_write.py                    |  6 +++++-
 8 files changed, 39 insertions(+), 16 deletions(-)

diff --git a/plugins/modules/vault_kv1_get.py b/plugins/modules/vault_kv1_get.py
index 0b69ae7dc..0921d6384 100644
--- a/plugins/modules/vault_kv1_get.py
+++ b/plugins/modules/vault_kv1_get.py
@@ -26,7 +26,8 @@
     description: Documentation for the Vault KV secrets engine, version 1.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v1
 extends_documentation_fragment:
-  - community.hashi_vault.action_group
+  - community.hashi_vault.attributes.action_group
+  - community.hashi_vault.attributes.check_mode_read_only
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount
diff --git a/plugins/modules/vault_kv2_delete.py b/plugins/modules/vault_kv2_delete.py
index cd3e71264..923eeb521 100644
--- a/plugins/modules/vault_kv2_delete.py
+++ b/plugins/modules/vault_kv2_delete.py
@@ -21,15 +21,19 @@
 notes:
   - This module always reports C(changed) status because it cannot guarantee idempotence.
   - Use C(changed_when) to control that in cases where the operation is known to not change state.
-  - In check mode, the module returns C(changed) status without contacting Vault.
-    Consider using M(community.hashi_vault.vault_kv2_get) to verify the existence of the secret first.
+attributes:
+  check_mode:
+    support: partial
+    description:
+      - In check mode, the module returns C(changed) status without contacting Vault.
+        Consider using M(community.hashi_vault.vault_kv2_get) to verify the existence of the secret first.
 seealso:
   - module: community.hashi_vault.vault_kv2_get
   - name: KV2 Secrets Engine
     description: Documentation for the Vault KV secrets engine, version 2.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v2
 extends_documentation_fragment:
-  - community.hashi_vault.action_group
+  - community.hashi_vault.attributes.action_group
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount
diff --git a/plugins/modules/vault_kv2_get.py b/plugins/modules/vault_kv2_get.py
index 0284efb07..07e6d7d69 100644
--- a/plugins/modules/vault_kv2_get.py
+++ b/plugins/modules/vault_kv2_get.py
@@ -26,7 +26,8 @@
     description: Documentation for the Vault KV secrets engine, version 2.
     link: https://www.vaultproject.io/docs/secrets/kv/kv-v2
 extends_documentation_fragment:
-  - community.hashi_vault.action_group
+  - community.hashi_vault.attributes.action_group
+  - community.hashi_vault.attributes.check_mode_read_only
   - community.hashi_vault.connection
   - community.hashi_vault.auth
   - community.hashi_vault.engine_mount
diff --git a/plugins/modules/vault_login.py b/plugins/modules/vault_login.py
index c43c9124f..5ff75cfe2 100644
--- a/plugins/modules/vault_login.py
+++ b/plugins/modules/vault_login.py
@@ -24,7 +24,7 @@
     - ref: community.hashi_vault.vault_login_token filter <ansible_collections.community.hashi_vault.vault_login_token_filter>
       description: The official documentation for the C(community.hashi_vault.vault_login_token) filter plugin.
   extends_documentation_fragment:
-    - community.hashi_vault.action_group
+    - community.hashi_vault.attributes.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
   notes:
@@ -37,9 +37,13 @@
     - "The C(token) auth method will only return full information if I(token_validate=True).
       If the token does not have the C(lookup-self) capability, this will fail. If I(token_validate=False), only the token value itself
       will be returned in the structure."
-    - "In check mode, this module will not perform a login, and will instead return a basic structure with an empty token.
-      However this may not be useful if the token is required for follow on tasks.
-      It may be better to use this module with C(check_mode=no) in order to have a valid token that can be used."
+  attributes:
+    check_mode:
+      support: partial
+      description:
+        - "In check mode, this module will not perform a login, and will instead return a basic structure with an empty token.
+          However this may not be useful if the token is required for follow on tasks.
+          It may be better to use this module with C(check_mode=no) in order to have a valid token that can be used."
   options:
     token_validate:
       description:
diff --git a/plugins/modules/vault_pki_generate_certificate.py b/plugins/modules/vault_pki_generate_certificate.py
index 0faabcf9c..030ff2f87 100644
--- a/plugins/modules/vault_pki_generate_certificate.py
+++ b/plugins/modules/vault_pki_generate_certificate.py
@@ -26,10 +26,14 @@
       description: HVAC library reference about the PKI engine.
       link: https://hvac.readthedocs.io/en/stable/usage/secrets_engines/pki.html#generate-certificate
   extends_documentation_fragment:
-    - community.hashi_vault.action_group
+    - community.hashi_vault.attributes.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.engine_mount
+  attributes:
+    check_mode:
+      support: partial
+      description: In check mode, this module will not contact Vault and will return an empty C(data) field and C(changed) status.
   options:
     alt_names:
       description:
diff --git a/plugins/modules/vault_read.py b/plugins/modules/vault_read.py
index 2aae6b2a9..fbb2f611b 100644
--- a/plugins/modules/vault_read.py
+++ b/plugins/modules/vault_read.py
@@ -24,7 +24,8 @@
     - ref: community.hashi_vault.hashi_vault lookup <ansible_collections.community.hashi_vault.hashi_vault_lookup>
       description: The official documentation for the C(community.hashi_vault.hashi_vault) lookup plugin.
   extends_documentation_fragment:
-    - community.hashi_vault.action_group
+    - community.hashi_vault.attributes.action_group
+    - community.hashi_vault.attributes.check_mode_read_only
     - community.hashi_vault.connection
     - community.hashi_vault.auth
   options:
diff --git a/plugins/modules/vault_token_create.py b/plugins/modules/vault_token_create.py
index a8edcc2ff..fe24cfde4 100644
--- a/plugins/modules/vault_token_create.py
+++ b/plugins/modules/vault_token_create.py
@@ -27,7 +27,7 @@
     - ref: community.hashi_vault.vault_login_token filter <ansible_collections.community.hashi_vault.vault_login_token_filter>
       description: The official documentation for the C(community.hashi_vault.vault_login_token) filter plugin.
   extends_documentation_fragment:
-    - community.hashi_vault.action_group
+    - community.hashi_vault.attributes.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.token_create
@@ -36,9 +36,13 @@
     - Token creation is a write operation (creating a token persisted to storage), so this module always reports C(changed=True).
     - For the purposes of Ansible playbooks however,
       it may be more useful to set I(changed_when=false) if you are doing idempotency checks against the target system.
-    - In check mode, this module will not create a token, and will instead return a basic structure with an empty token.
-      However, this may not be useful if the token is required for follow on tasks.
-      It may be better to use this module with I(check_mode=no) in order to have a valid token that can be used.
+  attributes:
+    check_mode:
+      support: partial
+      description:
+        - In check mode, this module will not create a token, and will instead return a basic structure with an empty token.
+          However, this may not be useful if the token is required for follow on tasks.
+          It may be better to use this module with I(check_mode=no) in order to have a valid token that can be used.
   options: {}
 """
 
diff --git a/plugins/modules/vault_write.py b/plugins/modules/vault_write.py
index a94349b36..a28c5e54d 100644
--- a/plugins/modules/vault_write.py
+++ b/plugins/modules/vault_write.py
@@ -23,6 +23,10 @@
     - The I(data) option is not treated as secret and may be logged. Use the C(no_log) keyword if I(data) contains sensitive values.
     - This module always reports C(changed) status because it cannot guarantee idempotence.
     - Use C(changed_when) to control that in cases where the operation is known to not change state.
+  attributes:
+    check_mode:
+      support: partial
+      description: In check mode, an empty response will be returned and the write will not be performed.
   seealso:
     - ref: community.hashi_vault.vault_write lookup <ansible_collections.community.hashi_vault.vault_write_lookup>
       description: The official documentation for the C(community.hashi_vault.vault_write) lookup plugin.
@@ -30,7 +34,7 @@
     - ref: community.hashi_vault.vault_read lookup <ansible_collections.community.hashi_vault.vault_read_lookup>
       description: The official documentation for the C(community.hashi_vault.vault_read) lookup plugin.
   extends_documentation_fragment:
-    - community.hashi_vault.action_group
+    - community.hashi_vault.attributes.action_group
     - community.hashi_vault.connection
     - community.hashi_vault.auth
     - community.hashi_vault.wrapping

From e81f963cb0c2b1b59fe543d4a96baa66d2887fe9 Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Fri, 4 Nov 2022 17:55:12 -0400
Subject: [PATCH 6/7] add changelog

---
 changelogs/fragments/197-module-attributes.yml | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 changelogs/fragments/197-module-attributes.yml

diff --git a/changelogs/fragments/197-module-attributes.yml b/changelogs/fragments/197-module-attributes.yml
new file mode 100644
index 000000000..2164cfd9c
--- /dev/null
+++ b/changelogs/fragments/197-module-attributes.yml
@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - modules - all modules now document their action group and support for check mode in their attributes documentation (https://github.com/ansible-collections/community.hashi_vault/issues/197).

From 2811949cc2ee101442ba73a1db4fb334bd6c3c1a Mon Sep 17 00:00:00 2001
From: Brian Scholer <1260690+briantist@users.noreply.github.com>
Date: Fri, 4 Nov 2022 18:19:54 -0400
Subject: [PATCH 7/7] missing options in fragment

---
 plugins/doc_fragments/attributes.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py
index 2914c986e..5ac6a5a30 100644
--- a/plugins/doc_fragments/attributes.py
+++ b/plugins/doc_fragments/attributes.py
@@ -15,6 +15,7 @@ class ModuleDocFragment(object):
 '''
 
     ACTION_GROUP = r'''
+options: {}
 attributes:
   action_group:
     description: Use C(group/community.hashi_vault.vault) in C(module_defaults) to set defaults for this module.
@@ -24,6 +25,7 @@ class ModuleDocFragment(object):
 '''
 
     CHECK_MODE_READ_ONLY = r'''
+options: {}
 attributes:
   check_mode:
     support: full