k*.py: normalize docs (#9391)

* k*.py: normalize docs * Update plugins/modules/keycloak_realm_keys_metadata_info.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/kibana_plugin.py Co-authored-by: Felix Fontein <felix@fontein.de> --------- Co-authored-by: Felix Fontein <felix@fontein.de>
2025-06-28 11:10:21 -07:00 · 2024-12-27 01:42:44 +13:00 · 2024-12-27 01:42:44 +13:00 · 49ed3d4acf
commit 49ed3d4acf
parent 6aadcc72d1
34 changed files with 4402 additions and 4882 deletions
--- a/plugins/modules/keycloak_realm_rolemapping.py
+++ b/plugins/modules/keycloak_realm_rolemapping.py
@ -8,8 +8,7 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type

-DOCUMENTATION = '''
---
+DOCUMENTATION = r"""
 module: keycloak_realm_rolemapping

 short_description: Allows administration of Keycloak realm role mappings into groups with the Keycloak API
@ -17,119 +16,104 @@ short_description: Allows administration of Keycloak realm role mappings into gr
 version_added: 8.2.0

 description:
-    - This module allows you to add, remove or modify Keycloak realm role
-      mappings into groups with the Keycloak REST API. It requires access to the
-      REST API via OpenID Connect; the user connecting and the client being used
-      must have the requisite access rights. In a default Keycloak installation,
-      admin-cli and an admin user would work, as would a separate client
-      definition with the scope tailored to your needs and a user having the
-      expected roles.
-
-    - The names of module options are snake_cased versions of the camelCase ones found in the
-      Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/18.0/rest-api/index.html).
-
-    - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
-      be returned that way by this module. You may pass single values for attributes when calling the module,
-      and this will be translated into a list suitable for the API.
-
-    - When updating a group_rolemapping, where possible provide the role ID to the module. This removes a lookup
-      to the API to translate the name into the role ID.
-
+  - This module allows you to add, remove or modify Keycloak realm role mappings into groups with the Keycloak REST API. It requires access to
+    the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak
+    installation, admin-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user
+    having the expected roles.
+  - The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation at
+    U(https://www.keycloak.org/docs-api/18.0/rest-api/index.html).
+  - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module.
+    You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API.
+  - When updating a group_rolemapping, where possible provide the role ID to the module. This removes a lookup to the API to translate the name
+    into the role ID.
 attributes:
-    check_mode:
-        support: full
-    diff_mode:
-        support: full
-    action_group:
-        version_added: 10.2.0
+  check_mode:
+    support: full
+  diff_mode:
+    support: full
+  action_group:
+    version_added: 10.2.0

 options:
-    state:
-        description:
-            - State of the realm_rolemapping.
-            - On C(present), the realm_rolemapping will be created if it does not yet exist, or updated with the parameters you provide.
-            - On C(absent), the realm_rolemapping will be removed if it exists.
-        default: 'present'
-        type: str
-        choices:
-            - present
-            - absent
+  state:
+    description:
+      - State of the realm_rolemapping.
+      - On C(present), the realm_rolemapping will be created if it does not yet exist, or updated with the parameters you provide.
+      - On C(absent), the realm_rolemapping will be removed if it exists.
+    default: 'present'
+    type: str
+    choices:
+      - present
+      - absent

-    realm:
+  realm:
+    type: str
+    description:
+      - They Keycloak realm under which this role_representation resides.
+    default: 'master'
+
+  group_name:
+    type: str
+    description:
+      - Name of the group to be mapped.
+      - This parameter is required (can be replaced by gid for less API call).
+  parents:
+    type: list
+    description:
+      - List of parent groups for the group to handle sorted top to bottom.
+      - Set this if your group is a subgroup and you do not provide the GID in O(gid).
+    elements: dict
+    suboptions:
+      id:
        type: str
        description:
-            - They Keycloak realm under which this role_representation resides.
-        default: 'master'
-
-    group_name:
+          - Identify parent by ID.
+          - Needs less API calls than using O(parents[].name).
+          - A deep parent chain can be started at any point when first given parent is given as ID.
+          - Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them,
+            with ID being preferred.
+      name:
        type: str
        description:
-            - Name of the group to be mapped.
-            - This parameter is required (can be replaced by gid for less API call).
-
-    parents:
-        type: list
-        description:
-            - List of parent groups for the group to handle sorted top to bottom.
-            - >-
-              Set this if your group is a subgroup and you do not provide the GID in O(gid).
-        elements: dict
-        suboptions:
-          id:
-            type: str
-            description:
-              - Identify parent by ID.
-              - Needs less API calls than using O(parents[].name).
-              - A deep parent chain can be started at any point when first given parent is given as ID.
-              - Note that in principle both ID and name can be specified at the same time
-                but current implementation only always use just one of them, with ID
-                being preferred.
-          name:
-            type: str
-            description:
-              - Identify parent by name.
-              - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
-              - When giving a parent chain with only names it must be complete up to the top.
-              - Note that in principle both ID and name can be specified at the same time
-                but current implementation only always use just one of them, with ID
-                being preferred.
-    gid:
+          - Identify parent by name.
+          - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood.
+          - When giving a parent chain with only names it must be complete up to the top.
+          - Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them,
+            with ID being preferred.
+  gid:
+    type: str
+    description:
+      - ID of the group to be mapped.
+      - This parameter is not required for updating or deleting the rolemapping but providing it will reduce the number of API calls required.
+  roles:
+    description:
+      - Roles to be mapped to the group.
+    type: list
+    elements: dict
+    suboptions:
+      name:
        type: str
        description:
-            - ID of the group to be mapped.
-            - This parameter is not required for updating or deleting the rolemapping but
-              providing it will reduce the number of API calls required.
-
-    roles:
+          - Name of the role_representation.
+          - This parameter is required only when creating or updating the role_representation.
+      id:
+        type: str
        description:
-            - Roles to be mapped to the group.
-        type: list
-        elements: dict
-        suboptions:
-            name:
-                type: str
-                description:
-                    - Name of the role_representation.
-                    - This parameter is required only when creating or updating the role_representation.
-            id:
-                type: str
-                description:
-                    - The unique identifier for this role_representation.
-                    - This parameter is not required for updating or deleting a role_representation but
-                      providing it will reduce the number of API calls required.
-
+          - The unique identifier for this role_representation.
+          - This parameter is not required for updating or deleting a role_representation but providing it will reduce the number of API calls
+            required.
 extends_documentation_fragment:
-    - community.general.keycloak
-    - community.general.keycloak.actiongroup_keycloak
-    - community.general.attributes
+  - community.general.keycloak
+  - community.general.keycloak.actiongroup_keycloak
+  - community.general.attributes

 author:
-    - Gaëtan Daubresse (@Gaetan2907)
-    - Marius Huysamen (@mhuysamen)
-    - Alexander Groß (@agross)
-'''
+  - Gaëtan Daubresse (@Gaetan2907)
+  - Marius Huysamen (@mhuysamen)
+  - Alexander Groß (@agross)
+"""

-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Map a client role to a group, authentication with credentials
  community.general.keycloak_realm_rolemapping:
    realm: MyCustomRealm
@ -195,49 +179,37 @@ EXAMPLES = '''
      - name: role_name2
        id: role_id2
  delegate_to: localhost
-'''
+"""

-RETURN = '''
+RETURN = r"""
 msg:
-    description: Message as to what action was taken.
-    returned: always
-    type: str
-    sample: "Role role1 assigned to group group1."
+  description: Message as to what action was taken.
+  returned: always
+  type: str
+  sample: "Role role1 assigned to group group1."

 proposed:
-    description: Representation of proposed client role mapping.
-    returned: always
-    type: dict
-    sample: {
-      clientId: "test"
-    }
+  description: Representation of proposed client role mapping.
+  returned: always
+  type: dict
+  sample: {clientId: "test"}

 existing:
-    description:
-      - Representation of existing client role mapping.
-      - The sample is truncated.
-    returned: always
-    type: dict
-    sample: {
-        "adminUrl": "http://www.example.com/admin_url",
-        "attributes": {
-            "request.object.signature.alg": "RS256",
-        }
-    }
+  description:
+    - Representation of existing client role mapping.
+    - The sample is truncated.
+  returned: always
+  type: dict
+  sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

 end_state:
-    description:
-      - Representation of client role mapping after module execution.
-      - The sample is truncated.
-    returned: on success
-    type: dict
-    sample: {
-        "adminUrl": "http://www.example.com/admin_url",
-        "attributes": {
-            "request.object.signature.alg": "RS256",
-        }
-    }
-'''
+  description:
+    - Representation of client role mapping after module execution.
+    - The sample is truncated.
+  returned: on success
+  type: dict
+  sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
+"""

 from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import (
    KeycloakAPI, keycloak_argument_spec, get_token, KeycloakError,