redfish modules: documentation language and formatting (#4722) (#4725)

* redfish_command: documentation language and formatting

Update the documentation block with more English language
more consistent with other modules and finish each description
with a full stop.

* redfish_command: do not end short desc in full stop

* redfish_command: remove more "the" on documentation

Remove "The" from beginning of descriptions.

* redfish_command: start documentation description with capital case

* redfish_config: update documentation language and format

Add full stops at end of descriptions, small updates to language,
ensure descriptions start with a capital case letter.

* redfish_config: documentation consistency

Use "username" for description similarly to redfish_command.

* redfish_info: documentation formatting and language

Update documentation block for consistency with other modules
with full stop at end of descriptions and small language updates.

* idrac_redfish_command: documentation formatting and language

Update documentation block for consistency with other modules
with full stop at end of descriptions and small language updates.

* idrac_redfish_command: more doc consistency fixes

Call it iDRAC everywhere and not sometimes OOB controller.

* idrac_redfish_command: documentation formatting and language

Update documentation block for consistency with other modules
with full stop at end of descriptions and small language updates.

* idrac_redfish_info: documentation formatting and language

Update documentation block for consistency with other modules
with full stop at end of descriptions and small language updates.

* ilo_redfish_config: documentation formatting and language

Update documentation block for consistency with other modules
with full stop at end of descriptions and small language updates.

* ilo_redfish_info: documentation formatting and language

Update documentation block for consistency with other modules
with full stop at end of descriptions and small language updates.

* idrac_redfish_info: documentation language

Call it "HTTP request" and not "URL request".

* idrac_redfish_command: documentation language fix

Call it "HTTP request" and not "URL request".

* idrac_redfish_config: documentation language fix

Call it "HTTP request" and not "URL request".

* redfish_command: documentation language fix

Call it "HTTP request" and not "URL request".

* redfish_config: documentation language fix

Call it "HTTP request" and not "URL request".

* redfish_info: documentation language fix

Call it "HTTP request" and not "URL request".

* redfish_command: documentation language fix

Boot device should be two words.

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 88cd35fd45)

Co-authored-by: bluikko <14869000+bluikko@users.noreply.github.com>

plugins/modules/remote_management/redfish/idrac_redfish_command.py

@@ -14,46 +14,46 @@ short_description: Manages Out-Of-Band controllers using iDRAC OEM Redfish APIs
 description:
   - Builds Redfish URIs locally and sends them to remote OOB controllers to
     perform an action.
-  - For use with Dell iDRAC operations that require Redfish OEM extensions
+  - For use with Dell iDRAC operations that require Redfish OEM extensions.
 options:
   category:
     required: true
     description:
-      - Category to execute on OOB controller
+      - Category to execute on iDRAC.
     type: str
   command:
     required: true
     description:
-      - List of commands to execute on OOB controller
+      - List of commands to execute on iDRAC.
     type: list
     elements: str
   baseuri:
     required: true
     description:
-      - Base URI of OOB controller
+      - Base URI of iDRAC.
     type: str
   username:
     description:
-      - User for authentication with OOB controller
+      - Username for authenticating to iDRAC.
     type: str
   password:
     description:
-      - Password for authentication with OOB controller
+      - Password for authenticating to iDRAC.
     type: str
   auth_token:
     description:
-      - Security token for authentication with OOB controller
+      - Security token for authenticating to iDRAC.
     type: str
     version_added: 2.3.0
   timeout:
     description:
-      - Timeout in seconds for URL requests to OOB controller
+      - Timeout in seconds for HTTP requests to iDRAC.
     default: 10
     type: int
   resource_id:
     required: false
     description:
-      - The ID of the System, Manager or Chassis to modify
+      - ID of the System, Manager or Chassis to modify.
     type: str
     version_added: '0.2.0'
 

plugins/modules/remote_management/redfish/idrac_redfish_config.py

@@ -20,50 +20,50 @@ options:
     required: true
     type: str
     description:
-      - Category to execute on iDRAC
+      - Category to execute on iDRAC.
   command:
     required: true
     description:
-      - List of commands to execute on iDRAC
+      - List of commands to execute on iDRAC.
       - I(SetManagerAttributes), I(SetLifecycleControllerAttributes) and
         I(SetSystemAttributes) are mutually exclusive commands when C(category)
-        is I(Manager)
+        is I(Manager).
     type: list
     elements: str
   baseuri:
     required: true
     description:
-      - Base URI of iDRAC
+      - Base URI of iDRAC.
     type: str
   username:
     description:
-      - User for authentication with iDRAC
+      - Username for authenticating to iDRAC.
     type: str
   password:
     description:
-      - Password for authentication with iDRAC
+      - Password for authenticating to iDRAC.
     type: str
   auth_token:
     description:
-      - Security token for authentication with OOB controller
+      - Security token for authenticating to iDRAC.
     type: str
     version_added: 2.3.0
   manager_attributes:
     required: false
     description:
-      - dictionary of iDRAC attribute name and value pairs to update
+      - Dictionary of iDRAC attribute name and value pairs to update.
     default: {}
     type: 'dict'
     version_added: '0.2.0'
   timeout:
     description:
-      - Timeout in seconds for URL requests to iDRAC controller
+      - Timeout in seconds for HTTP requests to iDRAC.
     default: 10
     type: int
   resource_id:
     required: false
     description:
-      - The ID of the System, Manager or Chassis to modify
+      - ID of the System, Manager or Chassis to modify.
     type: str
     version_added: '0.2.0'
 

plugins/modules/remote_management/redfish/idrac_redfish_info.py

@@ -14,44 +14,44 @@ short_description: Gather PowerEdge server information through iDRAC using Redfi
 description:
   - Builds Redfish URIs locally and sends them to remote iDRAC controllers to
     get information back.
-  - For use with Dell EMC iDRAC operations that require Redfish OEM extensions
+  - For use with Dell EMC iDRAC operations that require Redfish OEM extensions.
   - This module was called C(idrac_redfish_facts) before Ansible 2.9, returning C(ansible_facts).
     Note that the M(community.general.idrac_redfish_info) module no longer returns C(ansible_facts)!
 options:
   category:
     required: true
     description:
-      - Category to execute on iDRAC controller
+      - Category to execute on iDRAC.
     type: str
   command:
     required: true
     description:
-      - List of commands to execute on iDRAC controller
+      - List of commands to execute on iDRAC.
       - C(GetManagerAttributes) returns the list of dicts containing iDRAC,
-        LifecycleController and System attributes
+        LifecycleController and System attributes.
     type: list
     elements: str
   baseuri:
     required: true
     description:
-      - Base URI of iDRAC controller
+      - Base URI of iDRAC.
     type: str
   username:
     description:
-      - User for authentication with iDRAC controller
+      - Username for authenticating to iDRAC.
     type: str
   password:
     description:
-      - Password for authentication with iDRAC controller
+      - Password for authenticating to iDRAC.
     type: str
   auth_token:
     description:
-      - Security token for authentication with OOB controller
+      - Security token for authenticating to iDRAC.
     type: str
     version_added: 2.3.0
   timeout:
     description:
-      - Timeout in seconds for URL requests to OOB controller
+      - Timeout in seconds for HTTP requests to iDRAC.
     default: 10
     type: int
 

plugins/modules/remote_management/redfish/ilo_redfish_config.py

@@ -34,19 +34,19 @@ options:
     type: str
   username:
     description:
-      - User for authentication with iLO.
+      - Username for authenticating to iLO.
     type: str
   password:
     description:
-      - Password for authentication with iLO.
+      - Password for authenticating to iLO.
     type: str
   auth_token:
     description:
-      - Security token for authentication with OOB controller.
+      - Security token for authenticating to iLO.
     type: str
   timeout:
     description:
-      - Timeout in seconds for URL requests to iLO controller.
+      - Timeout in seconds for HTTP requests to iLO.
     default: 10
     type: int
   attribute_name:

plugins/modules/remote_management/redfish/ilo_redfish_info.py

@@ -34,19 +34,19 @@ options:
     type: str
   username:
     description:
-      - User for authentication with iLO.
+      - Username for authenticating to iLO.
     type: str
   password:
     description:
-      - Password for authentication with iLO.
+      - Password for authenticating to iLO.
     type: str
   auth_token:
     description:
-      - Security token for authentication with iLO.
+      - Security token for authenticating to iLO.
     type: str
   timeout:
     description:
-      - Timeout in seconds for URL requests to iLO.
+      - Timeout in seconds for HTTP requests to iLO.
     default: 10
     type: int
 author:

plugins/modules/remote_management/redfish/redfish_command.py

@@ -21,35 +21,35 @@ options:
   category:
     required: true
     description:
-      - Category to execute on OOB controller
+      - Category to execute on OOB controller.
     type: str
   command:
     required: true
     description:
-      - List of commands to execute on OOB controller
+      - List of commands to execute on OOB controller.
     type: list
     elements: str
   baseuri:
     required: true
     description:
-      - Base URI of OOB controller
+      - Base URI of OOB controller.
     type: str
   username:
     description:
-      - Username for authentication with OOB controller
+      - Username for authenticating to OOB controller.
     type: str
   password:
     description:
-      - Password for authentication with OOB controller
+      - Password for authenticating to OOB controller.
     type: str
   auth_token:
     description:
-      - Security token for authentication with OOB controller
+      - Security token for authenticating to OOB controller.
     type: str
     version_added: 2.3.0
   session_uri:
     description:
-      - URI of the session resource
+      - URI of the session resource.
     type: str
     version_added: 2.3.0
   id:
@@ -63,28 +63,28 @@ options:
     required: false
     aliases: [ account_username ]
     description:
-      - Username of account to add/delete/modify
+      - Username of account to add/delete/modify.
     type: str
   new_password:
     required: false
     aliases: [ account_password ]
     description:
-      - New password of account to add/modify
+      - New password of account to add/modify.
     type: str
   roleid:
     required: false
     aliases: [ account_roleid ]
     description:
-      - Role of account to add/modify
+      - Role of account to add/modify.
     type: str
   bootdevice:
     required: false
     description:
-      - bootdevice when setting boot configuration
+      - Boot device when setting boot configuration.
     type: str
   timeout:
     description:
-      - Timeout in seconds for URL requests to OOB controller
+      - Timeout in seconds for HTTP requests to OOB controller.
     default: 10
     type: int
   boot_override_mode:
@@ -96,117 +96,117 @@ options:
   uefi_target:
     required: false
     description:
-      - UEFI target when bootdevice is "UefiTarget"
+      - UEFI boot target when bootdevice is "UefiTarget".
     type: str
   boot_next:
     required: false
     description:
-      - BootNext target when bootdevice is "UefiBootNext"
+      - BootNext target when bootdevice is "UefiBootNext".
     type: str
   update_username:
     required: false
     aliases: [ account_updatename ]
     description:
-      - new update user name for account_username
+      - New user name for updating account_username.
     type: str
     version_added: '0.2.0'
   account_properties:
     required: false
     description:
-      - properties of account service to update
+      - Properties of account service to update.
     type: dict
     version_added: '0.2.0'
   resource_id:
     required: false
     description:
-      - The ID of the System, Manager or Chassis to modify
+      - ID of the System, Manager or Chassis to modify.
     type: str
     version_added: '0.2.0'
   update_image_uri:
     required: false
     description:
-      - The URI of the image for the update
+      - URI of the image for the update.
     type: str
     version_added: '0.2.0'
   update_protocol:
     required: false
     description:
-      - The protocol for the update
+      - Protocol for the update.
     type: str
     version_added: '0.2.0'
   update_targets:
     required: false
     description:
-      - The list of target resource URIs to apply the update to
+      - List of target resource URIs to apply the update to.
     type: list
     elements: str
     version_added: '0.2.0'
   update_creds:
     required: false
     description:
-      - The credentials for retrieving the update image
+      - Credentials for retrieving the update image.
     type: dict
     version_added: '0.2.0'
     suboptions:
       username:
         required: false
         description:
-          - The username for retrieving the update image
+          - Username for retrieving the update image.
         type: str
       password:
         required: false
         description:
-          - The password for retrieving the update image
+          - Password for retrieving the update image.
         type: str
   virtual_media:
     required: false
     description:
-      - The options for VirtualMedia commands
+      - Options for VirtualMedia commands.
     type: dict
     version_added: '0.2.0'
     suboptions:
       media_types:
         required: false
         description:
-          - The list of media types appropriate for the image
+          - List of media types appropriate for the image.
         type: list
         elements: str
       image_url:
         required: false
         description:
-          - The URL of the image to insert or eject
+          - URL of the image to insert or eject.
         type: str
       inserted:
         required: false
         description:
-          - Indicates if the image is treated as inserted on command completion
+          - Indicates that the image is treated as inserted on command completion.
         type: bool
         default: True
       write_protected:
         required: false
         description:
-          - Indicates if the media is treated as write-protected
+          - Indicates that the media is treated as write-protected.
         type: bool
         default: True
       username:
         required: false
         description:
-          - The username for accessing the image URL
+          - Username for accessing the image URL.
         type: str
       password:
         required: false
         description:
-          - The password for accessing the image URL
+          - Password for accessing the image URL.
         type: str
       transfer_protocol_type:
         required: false
         description:
-          - The network protocol to use with the image
+          - Network protocol to use with the image.
         type: str
       transfer_method:
         required: false
         description:
-          - The transfer method to use with the image
+          - Transfer method to use with the image.
         type: str
   strip_etag_quotes:
     description:

plugins/modules/remote_management/redfish/redfish_config.py

@@ -20,48 +20,48 @@ options:
   category:
     required: true
     description:
-      - Category to execute on OOB controller
+      - Category to execute on OOB controller.
     type: str
   command:
     required: true
     description:
-      - List of commands to execute on OOB controller
+      - List of commands to execute on OOB controller.
     type: list
     elements: str
   baseuri:
     required: true
     description:
-      - Base URI of OOB controller
+      - Base URI of OOB controller.
     type: str
   username:
     description:
-      - User for authentication with OOB controller
+      - Username for authenticating to OOB controller.
     type: str
   password:
     description:
-      - Password for authentication with OOB controller
+      - Password for authenticating to OOB controller.
     type: str
   auth_token:
     description:
-      - Security token for authentication with OOB controller
+      - Security token for authenticating to OOB controller.
     type: str
     version_added: 2.3.0
   bios_attributes:
     required: false
     description:
-      - dictionary of BIOS attributes to update
+      - Dictionary of BIOS attributes to update.
     default: {}
     type: dict
     version_added: '0.2.0'
   timeout:
     description:
-      - Timeout in seconds for URL requests to OOB controller
+      - Timeout in seconds for HTTP requests to OOB controller.
     default: 10
     type: int
   boot_order:
     required: false
     description:
-      - list of BootOptionReference strings specifying the BootOrder
+      - List of BootOptionReference strings specifying the BootOrder.
     default: []
     type: list
     elements: str
@@ -69,26 +69,26 @@ options:
   network_protocols:
     required: false
     description:
-      -  setting dict of manager services to update
+      - Setting dict of manager services to update.
     type: dict
     version_added: '0.2.0'
   resource_id:
     required: false
     description:
-      - The ID of the System, Manager or Chassis to modify
+      - ID of the System, Manager or Chassis to modify.
     type: str
     version_added: '0.2.0'
   nic_addr:
     required: false
     description:
-      - EthernetInterface Address string on OOB controller
+      - EthernetInterface Address string on OOB controller.
     default: 'null'
     type: str
     version_added: '0.2.0'
   nic_config:
     required: false
     description:
-      - setting dict of EthernetInterface on OOB controller
+      - Setting dict of EthernetInterface on OOB controller.
     type: dict
     version_added: '0.2.0'
   strip_etag_quotes:

plugins/modules/remote_management/redfish/redfish_info.py

@@ -21,37 +21,37 @@ options:
   category:
     required: false
     description:
-      - List of categories to execute on OOB controller
+      - List of categories to execute on OOB controller.
     default: ['Systems']
     type: list
     elements: str
   command:
     required: false
     description:
-      - List of commands to execute on OOB controller
+      - List of commands to execute on OOB controller.
     type: list
     elements: str
   baseuri:
     required: true
     description:
-      - Base URI of OOB controller
+      - Base URI of OOB controller.
     type: str
   username:
     description:
-      - User for authentication with OOB controller
+      - Username for authenticating to OOB controller.
     type: str
   password:
     description:
-      - Password for authentication with OOB controller
+      - Password for authenticating to OOB controller.
     type: str
   auth_token:
     description:
-      - Security token for authentication with OOB controller
+      - Security token for authenticating to OOB controller.
     type: str
     version_added: 2.3.0
   timeout:
     description:
-      - Timeout in seconds for URL requests to OOB controller
+      - Timeout in seconds for HTTP requests to OOB controller.
     default: 10
     type: int