Fix tagging in documentation strings (#10)

.github/workflows/update-pre-commit.yml

@@ -7,6 +7,8 @@ on:
 
 jobs:
   pre-commit:
+    permissions:
+      contents: write
     uses:
       redhat-cop/ansible_collections_tooling/.github/workflows/update_precommit.yml@main
     with:

plugins/doc_fragments/auth.py

@@ -15,7 +15,7 @@ class ModuleDocFragment(object):
   quay_host:
     description:
       - URL for accessing the API. U(https://quay.example.com:8443) for example.
-      - If you do not set the parameter, then the module uses the C(QUAY_HOST)
+      - If you do not set the parameter, then the module uses the E(QUAY_HOST)
         environment variable.
       - If you do no set the environment variable either, then the module uses
         the U(http://127.0.0.1) URL.
@@ -24,12 +24,12 @@ class ModuleDocFragment(object):
   validate_certs:
     description:
       - Whether to allow insecure connections to the API.
-      - If C(no), then the module does not validate SSL certificates.
+      - If V(false), then the module does not validate SSL certificates.
       - If you do not set the parameter, then the module tries the
-        C(QUAY_VERIFY_SSL) environment variable (C(yes), C(1), and C(True) mean
-        yes, and C(no), C(0), C(False), and no value mean no).
+        E(QUAY_VERIFY_SSL) environment variable (V(yes), V(1), and V(True) mean
+        true, and V(no), V(0), V(False), and no value mean false).
     type: bool
-    default: yes
+    default: true
     aliases: [verify_ssl]
 """
 
@@ -38,24 +38,24 @@ class ModuleDocFragment(object):
   quay_token:
     description:
       - OAuth access token for authenticating against the API.
-      - If you do not set the parameter, then the module tries the C(QUAY_TOKEN)
+      - If you do not set the parameter, then the module tries the E(QUAY_TOKEN)
         environment variable.
-      - Mutually exclusive with I(quay_username) and I(quay_password).
+      - Mutually exclusive with O(quay_username) and O(quay_password).
     type: str
   quay_username:
     description:
       - The username to use for authenticating against the API.
       - If you do not set the parameter, then the module tries the
-        C(QUAY_USERNAME) environment variable.
-      - If you set I(quay_username), then you also need to set I(quay_password).
-      - Mutually exclusive with I(quay_token).
+        E(QUAY_USERNAME) environment variable.
+      - If you set O(quay_username), then you also need to set O(quay_password).
+      - Mutually exclusive with O(quay_token).
     type: str
   quay_password:
     description:
       - The password to use for authenticating against the API.
       - If you do not set the parameter, then the module tries the
-        C(QUAY_PASSWORD) environment variable.
-      - If you set I(quay_password), then you also need to set I(quay_username).
-      - Mutually exclusive with I(quay_token).
+        E(QUAY_PASSWORD) environment variable.
+      - If you set O(quay_password), then you also need to set O(quay_username).
+      - Mutually exclusive with O(quay_token).
     type: str
 """

plugins/doc_fragments/autoprune.py

@@ -15,29 +15,29 @@ class ModuleDocFragment(object):
   auto_prune_method:
     description:
       - Method to use for the auto-pruning tags policy.
-      - If C(none), then the module ensures that no policy is in place. The
+      - If V(none), then the module ensures that no policy is in place. The
         tags are not pruned.
-      - If C(tags), then the policy keeps only the number of tags that you
-        specify in I(auto_prune_value).
-      - If C(date), then the policy deletes the tags older than the time period
-        that you specify in I(auto_prune_value).
-      - I(auto_prune_value) is required when I(auto_prune_method) is C(tags) or
-        C(date).
+      - If V(tags), then the policy keeps only the number of tags that you
+        specify in O(auto_prune_value).
+      - If V(date), then the policy deletes the tags older than the time period
+        that you specify in O(auto_prune_value).
+      - O(auto_prune_value) is required when O(auto_prune_method) is V(tags) or
+        V(date).
     type: str
     choices: [none, tags, date]
   auto_prune_value:
     description:
-      - Number of tags to keep when I(auto_prune_value) is C(tags).
+      - Number of tags to keep when O(auto_prune_method) is V(tags).
         The value must be 1 or more.
-      - Period of time when I(auto_prune_value) is C(date). The value must be 1
+      - Period of time when O(auto_prune_method) is V(date). The value must be 1
         or more, and must be followed by a suffix; s (for second), m (for
         minute), h (for hour), d (for day), or w (for week).
-      - I(auto_prune_method) is required when I(auto_prune_value) is set.
+      - O(auto_prune_method) is required when O(auto_prune_value) is set.
     type: str
 notes:
   - Your Quay administrator must enable the auto-prune capability of your Quay
     installation (C(FEATURE_AUTO_PRUNE) in C(config.yaml)) to use the
-    I(auto_prune_method) and I(auto_prune_value) parameters.
-  - Using I(auto_prune_method) and I(auto_prune_value) requires Quay version
+    O(auto_prune_method) and O(auto_prune_value) parameters.
+  - Using O(auto_prune_method) and O(auto_prune_value) requires Quay version
     3.11 or later.
 """

plugins/modules/quay_api_token.py

@@ -32,14 +32,14 @@
     description:
       - The username to use for authenticating against the API.
       - If you do not set the parameter, then the module tries the
-        C(QUAY_USERNAME) environment variable.
+        E(QUAY_USERNAME) environment variable.
     type: str
     required: true
   quay_password:
     description:
       - The password to use for authenticating against the API.
       - If you do not set the parameter, then the module tries the
-        C(QUAY_PASSWORD) environment variable.
+        E(QUAY_PASSWORD) environment variable.
     type: str
     required: true
   client_id:
@@ -52,7 +52,7 @@
     type: str
   rights:
     description:
-      - List of permissions to grant to the user account. C(all) means all the
+      - List of permissions to grant to the user account. V(all) means all the
         permissions.
     type: list
     elements: str
@@ -78,12 +78,12 @@
     required: false
 notes:
   - Supports C(check_mode).
-  - I(for_user) requires Quay version 3.12 or later.
+  - 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))
-    to use the I(for_user) option in Quay version 3.12 or later.
+    to use the O(for_user) option in Quay version 3.12 or later.
   - The generated OAuth access token acts on behalf of the user account you use
-    with the module (in I(for_user) if set, otherwise in I(quay_username)).
+    with the module (in O(for_user) if set, otherwise in O(quay_username)).
   - The user must have admin rights to the application's organization, by being
     the creator of this organization, or by belonging to a team with admin
     rights.
@@ -186,7 +186,7 @@
 RETURN = r"""
 access_token:
   description: The OAuth access token.
-  returned: only when I(for_user) is not set
+  returned: only when O(for_user) is not set
   type: str
   sample: CywbRGkh1ttYkRRy9VL0Aw0yU9q7J62vIeo7WCFw
  """

plugins/modules/quay_application.py

@@ -45,7 +45,7 @@
     description:
       - New name for the application.
       - Setting this option changes the name of the application which current
-        name is provided in I(name).
+        name is provided in O(name).
     type: str
   description:
     description:
@@ -65,18 +65,18 @@
     type: str
   state:
     description:
-      - If C(absent), then the module deletes the application.
+      - If V(absent), then the module deletes the application.
       - The module does not fail if the application does not exist, because the
         state is already as expected.
-      - If C(present), then the module creates the application if it does not
+      - If V(present), then the module creates the application if it does not
         already exist.
       - If the application already exists, then the module updates its state.
     type: str
     default: present
     choices: [absent, present]
 notes:
   - Supports C(check_mode).
-  - The token that you provide in I(quay_token) must have the "Administer
+  - The token that you provide in O(quay_token) must have the "Administer
     Organization" permission.
 extends_documentation_fragment:
   - infra.quay_configuration.auth

plugins/modules/quay_default_perm.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2021, 2022 Hervé Quatremain <[email protected]>
+# Copyright: (c) 2021, 2022, 2024 Hervé Quatremain <[email protected]>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # For accessing the API documentation from a running system, use the swagger-ui
@@ -48,7 +48,7 @@
     type: str
   type:
     description:
-      - Type of the account defined in I(name). Choose C(user)
+      - Type of the account defined in O(name). Choose V(user)
         for both user and robot accounts.
     type: str
     choices: [user, team]
@@ -57,33 +57,33 @@
     description:
       - Permission that Quay automatically grants to the user or team on new
         created repositories in the organization.
-      - If you do not provide that parameter, then the module uses C(read) by
+      - If you do not provide that parameter, then the module uses V(read) by
         default.
     type: str
     choices: [read, write, admin]
   creator:
     description:
       - Quay applies the default permission only when repositories are created
-        by the user that you define in I(creator).
-      - By default, if you do not provide that I(creator) parameter, then Quay
+        by the user that you define in O(creator).
+      - By default, if you do not provide that O(creator) parameter, then Quay
         applies the default permission to all new repositories, whoever creates
         them.
-      - You cannot use robot accounts or teams for the I(creator) parameter.
+      - You cannot use robot accounts or teams for the O(creator) parameter.
         You can only use regular user accounts.
     type: str
   state:
     description:
-      - If C(absent), then the module deletes the default permission.
-      - If C(present), then the module creates the default permission if it
+      - If V(absent), then the module deletes the default permission.
+      - If V(present), then the module creates the default permission if it
         does not already exist.
       - If the default permission already exists, then the module updates its
-        role parameter (C(read), C(write), or C(admin)).
+        role parameter (V(read), V(write), or V(admin)).
     type: str
     default: present
     choices: [absent, present]
 notes:
   - Supports C(check_mode).
-  - The token that you provide in I(quay_token) must have the "Administer
+  - The token that you provide in O(quay_token) must have the "Administer
     Organization" and "Administer User" permissions.
 extends_documentation_fragment:
   - infra.quay_configuration.auth

plugins/modules/quay_docker_token.py

@@ -44,10 +44,10 @@
     type: str
   state:
     description:
-      - If C(absent), then the module deletes the token.
+      - If V(absent), then the module deletes the token.
       - The module does not fail if the token does not exist, because the
         state is already as expected.
-      - If C(present), then the module creates the token if it does not
+      - If V(present), then the module creates the token if it does not
         already exist.
       - If the token already exists, then the module returns its details.
     type: str
@@ -139,14 +139,14 @@
 last_accessed:
   description:
     - Last date and time the token was used.
-    - If the token has not been used yet, then I(last_accessed) is C(null).
+    - If the token has not been used yet, then RV(last_accessed) is V(null).
   returned: always
   type: str
   sample: Wed, 25 May 2022 12:49:45 -0000
 expiration:
   description:
     - Expiration date and time of the token.
-    - By default, tokens do not expire. In that case I(expiration) is C(null).
+    - By default, tokens do not expire. In that case RV(expiration) is V(null).
     - Your Quay administrator might have activated expiration by setting the
       C(APP_SPECIFIC_TOKEN_EXPIRATION) directive in the C(config.yaml)
       configuration file.

plugins/modules/quay_first_user.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2021, 2022 Hervé Quatremain <[email protected]>
+# Copyright: (c) 2021, 2022, 2024 Hervé Quatremain <[email protected]>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # For accessing the API documentation from a running system, use the swagger-ui
@@ -46,16 +46,16 @@
       - You probably want that user account to have superuser permissions so
         that you can use the returned token to create additional objects.
         To do so, add the account name to the C(SUPER_USERS) section in the
-        C(config.yaml) file before using the M(infra.quay_configuration.quay_first_user)
-        module.
+        C(config.yaml) file before using the
+        M(infra.quay_configuration.quay_first_user) module.
     required: true
     type: str
   email:
     description:
       - User's email address.
       - If your Quay administrator has enabled the mailing capability of your
         Quay installation (C(FEATURE_MAILING) to C(true) in C(config.yaml)),
-        then this I(email) parameter is mandatory.
+        then this O(email) parameter is mandatory.
     type: str
   password:
     description:
@@ -66,12 +66,12 @@
     type: str
   create_token:
     description:
-      - If C(yes), then an OAuth access token is created and returned. You can
+      - If V(true), then an OAuth access token is created and returned. You can
         use that returned token with the other Quay modules, by setting it in
-        the I(quay_token) parameter. The token is valid for 2 hours 30 minutes.
-      - If C(no), then no access token is created.
+        the C(quay_token) parameter. The token is valid for 2 hours 30 minutes.
+      - If V(false), then no access token is created.
     type: bool
-    default: no
+    default: false
 notes:
   - The module requires Quay version 3.6 or later.
   - To use the module, you must enable the first user creation feature of your
@@ -104,7 +104,7 @@
   description:
     - The access token that you can use for subsequent module calls.
     - The token is valid for 2 hours 30 minutes.
-  returned: only when you set the I(create_token) parameter to C(yes)
+  returned: only when you set the O(create_token) parameter to V(true)
   type: str
   sample: W2YX0V838JZ5FHHUH82Q25FZZMRX8YTB1MTN56P3
 email:

plugins/modules/quay_manifest_label.py

@@ -47,24 +47,24 @@
     type: str
   value:
     description:
-      - Label's value. Required when C(state=present).
+      - Label's value. Required when O(state=present).
     type: str
   replace:
     description:
-      - Only used when C(state=present).
-      - If C(yes), then the module deletes all the labels that use the key you
-        define in the I(key) parameter before adding the new label.
-      - If C(no), then the module adds the new label even if existing labels
-        already use the key you define in the I(key) parameter. Quay supports
+      - Only used when O(state=present).
+      - If V(true), then the module deletes all the labels that use the key you
+        define in the O(key) parameter before adding the new label.
+      - If V(false), then the module adds the new label even if existing labels
+        already use the key you define in the O(key) parameter. Quay supports
         multiple labels with the same key.
     type: bool
-    default: yes
+    default: true
   state:
     description:
-      - If C(absent), then the module deletes the labels that match the I(key)
-        and I(value) parameters. If you do not provide the I(value) parameter,
-        then the module deletes all the labels with the I(key) parameter.
-      - If C(present), then the module adds a label to the manifest.
+      - If V(absent), then the module deletes the labels that match the O(key)
+        and O(value) parameters. If you do not provide the O(value) parameter,
+        then the module deletes all the labels with the O(key) parameter.
+      - If V(present), then the module adds a label to the manifest.
     type: str
     default: present
     choices: [absent, present]
@@ -73,7 +73,7 @@
     updated. They are read-only.
   - Supports C(check_mode).
   - The user account associated with the token that you provide in
-    I(quay_token) must have write access to the repository.
+    O(quay_token) must have write access to the repository.
 extends_documentation_fragment:
   - infra.quay_configuration.auth
   - infra.quay_configuration.auth.login
@@ -136,13 +136,13 @@
 source_type:
   description:
     - Whether the label has been set by the Containerfile/Dockerfile manifest
-      (C(manifest)), or by an API call or from the web UI (C(api)).
+      (V(manifest)), or by an API call or from the web UI (V(api)).
     - Labels set in Containerfile/Dockerfile manifests are read-only.
   returned: always
   type: str
   sample: api
 media_type:
-  description: Format of the label (C(text/plain) or C(application/json)).
+  description: Format of the label (V(text/plain) or V(application/json)).
   returned: always
   type: str
   sample: text/plain