[PR #9418/43599c68 backport][stable-10] c*.py: normalize docs (#9426)

c*.py: normalize docs (#9418) * c*.py: normalize docs * fix copy/paste mistake * Apply suggestions from code review Co-authored-by: Felix Fontein <[email protected]> --------- Co-authored-by: Felix Fontein <[email protected]> (cherry picked from commit 43599c6) Co-authored-by: Alexei Znamensky <[email protected]>
ansible-collections · Dec 27, 2024 · 3db0a11 · 3db0a11
1 parent 05ba79c
commit 3db0a11
Show file tree

Hide file tree

Showing 36 changed files with 1,450 additions and 1,627 deletions.
diff --git a/plugins/modules/campfire.py b/plugins/modules/campfire.py
@@ -9,15 +9,14 @@
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: campfire
 short_description: Send a message to Campfire
 description:
-   - Send a message to Campfire.
-   - Messages with newlines will result in a "Paste" message being sent.
+  - Send a message to Campfire.
+  - Messages with newlines will result in a "Paste" message being sent.
 extends_documentation_fragment:
-   - community.general.attributes
+  - community.general.attributes
 attributes:
   check_mode:
     support: none
@@ -49,22 +48,17 @@
     description:
       - Send a notification sound before the message.
     required: false
-    choices: ["56k", "bell", "bezos", "bueller", "clowntown",
-              "cottoneyejoe", "crickets", "dadgummit", "dangerzone",
-              "danielsan", "deeper", "drama", "greatjob", "greyjoy",
-              "guarantee", "heygirl", "horn", "horror",
-              "inconceivable", "live", "loggins", "makeitso", "noooo",
-              "nyan", "ohmy", "ohyeah", "pushit", "rimshot",
-              "rollout", "rumble", "sax", "secret", "sexyback",
-              "story", "tada", "tmyk", "trololo", "trombone", "unix",
-              "vuvuzela", "what", "whoomp", "yeah", "yodel"]
+    choices: ["56k", "bell", "bezos", "bueller", "clowntown", "cottoneyejoe", "crickets", "dadgummit", "dangerzone", "danielsan",
+      "deeper", "drama", "greatjob", "greyjoy", "guarantee", "heygirl", "horn", "horror", "inconceivable", "live", "loggins",
+      "makeitso", "noooo", "nyan", "ohmy", "ohyeah", "pushit", "rimshot", "rollout", "rumble", "sax", "secret", "sexyback",
+      "story", "tada", "tmyk", "trololo", "trombone", "unix", "vuvuzela", "what", "whoomp", "yeah", "yodel"]
 
 # informational: requirements for nodes
-requirements: [ ]
+requirements: []
 author: "Adam Garside (@fabulops)"
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Send a message to Campfire
   community.general.campfire:
     subscription: foo
@@ -79,7 +73,7 @@
     room: 123
     notify: loggins
     msg: Task completed ... with feeling.
-'''
+"""
 
 try:
     from html import escape as html_escape

diff --git a/plugins/modules/capabilities.py b/plugins/modules/capabilities.py
@@ -8,48 +8,47 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
 module: capabilities
 short_description: Manage Linux capabilities
 description:
-    - This module manipulates files privileges using the Linux capabilities(7) system.
+  - This module manipulates files privileges using the Linux capabilities(7) system.
 extends_documentation_fragment:
-    - community.general.attributes
+  - community.general.attributes
 attributes:
-    check_mode:
-        support: full
-    diff_mode:
-        support: none
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
 options:
-    path:
-        description:
-            - Specifies the path to the file to be managed.
-        type: str
-        required: true
-        aliases: [ key ]
-    capability:
-        description:
-            - Desired capability to set (with operator and flags, if O(state=present)) or remove (if O(state=absent))
-        type: str
-        required: true
-        aliases: [ cap ]
-    state:
-        description:
-            - Whether the entry should be present or absent in the file's capabilities.
-        type: str
-        choices: [ absent, present ]
-        default: present
+  path:
+    description:
+      - Specifies the path to the file to be managed.
+    type: str
+    required: true
+    aliases: [key]
+  capability:
+    description:
+      - Desired capability to set (with operator and flags, if O(state=present)) or remove (if O(state=absent)).
+    type: str
+    required: true
+    aliases: [cap]
+  state:
+    description:
+      - Whether the entry should be present or absent in the file's capabilities.
+    type: str
+    choices: [absent, present]
+    default: present
 notes:
-    - The capabilities system will automatically transform operators and flags into the effective set,
-      so for example, C(cap_foo=ep) will probably become C(cap_foo+ep).
-    - This module does not attempt to determine the final operator and flags to compare,
-      so you will want to ensure that your capabilities argument matches the final capabilities.
+  - The capabilities system will automatically transform operators and flags into the effective set, so for example, C(cap_foo=ep)
+    will probably become C(cap_foo+ep).
+  - This module does not attempt to determine the final operator and flags to compare, so you will want to ensure that your
+    capabilities argument matches the final capabilities.
 author:
-- Nate Coraor (@natefoo)
-'''
+  - Nate Coraor (@natefoo)
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Set cap_sys_chroot+ep on /foo
   community.general.capabilities:
     path: /foo
@@ -61,7 +60,7 @@
     path: /bar
     capability: cap_net_bind_service
     state: absent
-'''
+"""
 
 from ansible.module_utils.basic import AnsibleModule
 

diff --git a/plugins/modules/cargo.py b/plugins/modules/cargo.py
@@ -11,7 +11,6 @@
 
 
 DOCUMENTATION = r"""
----
 module: cargo
 short_description: Manage Rust packages with cargo
 version_added: 4.3.0
@@ -39,16 +38,12 @@
     elements: str
     required: true
   path:
-    description:
-      ->
-      The base path where to install the Rust packages. Cargo automatically appends
-      V(/bin). In other words, V(/usr/local) will become V(/usr/local/bin).
+    description: The base path where to install the Rust packages. Cargo automatically appends V(/bin). In other words,
+      V(/usr/local) will become V(/usr/local/bin).
     type: path
   version:
-    description:
-      ->
-      The version to install. If O(name) contains multiple values, the module will
-      try to install all of them in this version.
+    description: The version to install. If O(name) contains multiple values, the module will try to install all of them
+      in this version.
     type: str
     required: false
   locked:
@@ -65,7 +60,7 @@
     required: false
     type: str
     default: present
-    choices: [ "present", "absent", "latest" ]
+    choices: ["present", "absent", "latest"]
   directory:
     description:
       - Path to the source directory to install the Rust package from.
@@ -74,7 +69,7 @@
     required: false
     version_added: 9.1.0
 requirements:
-    - cargo installed
+  - cargo installed
 """
 
 EXAMPLES = r"""

diff --git a/plugins/modules/catapult.py b/plugins/modules/catapult.py
@@ -11,14 +11,13 @@
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: catapult
-short_description: Send a sms / mms using the catapult bandwidth api
+short_description: Send a sms / mms using the catapult bandwidth API
 description:
-    - Allows notifications to be sent using sms / mms via the catapult bandwidth api.
+  - Allows notifications to be sent using SMS / MMS using the catapult bandwidth API.
 extends_documentation_fragment:
-    - community.general.attributes
+  - community.general.attributes
 attributes:
   check_mode:
     support: none
@@ -44,31 +43,30 @@
   media:
     type: str
     description:
-      - For MMS messages, a media url to the location of the media to be sent with the message.
+      - For MMS messages, a media URL to the location of the media to be sent with the message.
   user_id:
     type: str
     description:
-      - User Id from Api account page.
+      - User Id from API account page.
     required: true
   api_token:
     type: str
     description:
-      - Api Token from Api account page.
+      - API Token from API account page.
     required: true
   api_secret:
     type: str
     description:
-      - Api Secret from Api account page.
+      - API Secret from API account page.
     required: true
 
 author: "Jonathan Mainguy (@Jmainguy)"
 notes:
-    - Will return changed even if the media url is wrong.
-    - Will return changed if the destination number is invalid.
+  - Will return changed even if the media url is wrong.
+  - Will return changed if the destination number is invalid.
+"""
 
-'''
-
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Send a mms to multiple users
   community.general.catapult:
     src: "+15035555555"
@@ -89,16 +87,15 @@
     user_id: "{{ user_id }}"
     api_token: "{{ api_token }}"
     api_secret: "{{ api_secret }}"
+"""
 
-'''
-
-RETURN = '''
+RETURN = r"""
 changed:
-    description: Whether the api accepted the message.
-    returned: always
-    type: bool
-    sample: true
-'''
+  description: Whether the API accepted the message.
+  returned: always
+  type: bool
+  sample: true
+"""
 
 
 import json