Repository: ansible/ansible
Pull request: add suboptions in ovirt docs
##### SUMMARY
<!--- Describe the change below, including rationale and design decisions -->
Fixes #53797 

First part of suboptions.

<!--- HINT: Include "Fixes #nnn" if you are fixing an existing issue -->

##### ISSUE TYPE
<!--- Pick one below and delete the rest -->
- Docs Pull Request

##### COMPONENT NAME
<!--- Write the short name of the module, plugin, task or feature below -->
ovirt
##### ADDITIONAL INFORMATION
<!--- Include additional information to help people understand the change here -->
<!--- A step-by-step reproduction of the problem is helpful if there is no related issue -->

<!--- Paste verbatim command output below, e.g. before and after your change -->
```paste below

```


Problem statement:
Use suboptions in oVirt modules doc
<!--- Verify first that your improvement is not already reported on GitHub -->
<!--- Also test if the latest release and devel branch are affected too -->
<!--- Complete *all* sections as described, this form is processed automatically -->

##### SUMMARY
<!--- Explain the problem briefly below, add suggestions to wording or structure -->
Use suboptions in oVirt module documentations of dictionary parameters.

<!--- HINT: Did you know the documentation has an "Edit on GitHub" link on every page ? -->

##### ISSUE TYPE
- Documentation Report

##### COMPONENT NAME
<!--- Write the short name of the rst file, module, plugin, task or feature below, use your best guess if unsure -->
ovirt

##### ANSIBLE VERSION
<!--- Paste verbatim output from "ansible --version" between quotes -->
```paste below

```

##### CONFIGURATION
<!--- Paste verbatim output from "ansible-config dump --only-changed" between quotes -->
```paste below

```

##### OS / ENVIRONMENT
<!--- Provide all relevant information below, e.g. OS version, browser, etc. -->

##### ADDITIONAL INFORMATION
<!--- Describe how this improves the documentation, e.g. before/after situation or screenshots -->

<!--- HINT: You can paste gist.github.com links for larger files -->

Hints from issue discussion:
Files identified in the description:
* [lib/ansible/module_utils/ovirt.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/module_utils/ovirt.py)

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
cc @mnecas @mwperina
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: notify --->

Commit message: add suboptions in doc_fragments/ovirt

Patch to review:
diff --git a/lib/ansible/plugins/doc_fragments/ovirt.py b/lib/ansible/plugins/doc_fragments/ovirt.py
index a47e6e2841d342..ac155ba25d9270 100644
--- a/lib/ansible/plugins/doc_fragments/ovirt.py
+++ b/lib/ansible/plugins/doc_fragments/ovirt.py
@@ -30,25 +30,46 @@ class ModuleDocFragment(object):
     auth:
         description:
             - "Dictionary with values needed to create HTTP/HTTPS connection to oVirt:"
-            - C(username)[I(required)] - The name of the user, something like I(admin@internal).
-              Default value is set by I(OVIRT_USERNAME) environment variable.
-            - "C(password)[I(required)] - The password of the user. Default value is set by I(OVIRT_PASSWORD) environment variable."
-            - "C(url) - A string containing the API URL of the server, usually
-            something like `I(https://server.example.com/ovirt-engine/api)`. Default value is set by I(OVIRT_URL) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(hostname) - A string containing the hostname of the server, usually
-            something like `I(server.example.com)`. Default value is set by I(OVIRT_HOSTNAME) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(token) - Token to be used instead of login with username/password. Default value is set by I(OVIRT_TOKEN) environment variable."
-            - "C(insecure) - A boolean flag that indicates if the server TLS
-            certificate and host name should be checked."
-            - "C(ca_file) - A PEM file containing the trusted CA certificates. The
-            certificate presented by the server will be verified using these CA
-            certificates. If `C(ca_file)` parameter is not set, system wide
-            CA certificate store is used. Default value is set by I(OVIRT_CAFILE) environment variable."
-            - "C(kerberos) - A boolean flag indicating if Kerberos authentication
-            should be used instead of the default basic authentication."
-            - "C(headers) - Dictionary of HTTP headers to be added to each API call."
+        suboptions:
+            username:
+                description:
+                    - The name of the user, something like I(admin@internal).
+                    - Default value is set by I(OVIRT_USERNAME) environment variable.
+                required: true
+            password:
+                description:
+                    - The password of the user.
+                    - Default value is set by I(OVIRT_PASSWORD) environment variable.
+                required: true
+            url:
+                description:
+                    - A string containing the API URL of the server, usually something like `I(https://server.example.com/ovirt-engine/api)`.
+                    - Default value is set by I(OVIRT_URL) environment variable.
+                    - Either C(url) or C(hostname) is required.
+            hostname:
+                description:
+                    - A string containing the hostname of the server, usually something like `I(server.example.com)`.
+                    - Default value is set by I(OVIRT_HOSTNAME) environment variable.
+                    - Either C(url) or C(hostname) is required.
+            token:
+                description:
+                    - Token to be used instead of login with username/password.
+                    - Default value is set by I(OVIRT_TOKEN) environment variable.
+            insecure:
+                description:
+                    - A boolean flag that indicates if the server TLS certificate and host name should be checked.
+            ca_file:
+                description:
+                    - A PEM file containing the trusted CA certificates.
+                    - The certificate presented by the server will be verified using these CA certificates.
+                    - If `C(ca_file)` parameter is not set, system wide CA certificate store is used.
+                    - Default value is set by I(OVIRT_CAFILE) environment variable.
+            kerberos:
+                description:
+                    -  A boolean flag indicating if Kerberos authentication should be used instead of the default basic authentication.
+            headers:
+                description:
+                    - Dictionary of HTTP headers to be added to each API call.
         type: dict
         required: true
     timeout:


Code review comments:
diff_hunk: @@ -30,25 +30,46 @@ class ModuleDocFragment(object):
     auth:
         description:
             - "Dictionary with values needed to create HTTP/HTTPS connection to oVirt:"
-            - C(username)[I(required)] - The name of the user, something like I(admin@internal).
-              Default value is set by I(OVIRT_USERNAME) environment variable.
-            - "C(password)[I(required)] - The password of the user. Default value is set by I(OVIRT_PASSWORD) environment variable."
-            - "C(url) - A string containing the API URL of the server, usually
-            something like `I(https://server.example.com/ovirt-engine/api)`. Default value is set by I(OVIRT_URL) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(hostname) - A string containing the hostname of the server, usually
-            something like `I(server.example.com)`. Default value is set by I(OVIRT_HOSTNAME) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(token) - Token to be used instead of login with username/password. Default value is set by I(OVIRT_TOKEN) environment variable."
-            - "C(insecure) - A boolean flag that indicates if the server TLS
-            certificate and host name should be checked."
-            - "C(ca_file) - A PEM file containing the trusted CA certificates. The
-            certificate presented by the server will be verified using these CA
-            certificates. If `C(ca_file)` parameter is not set, system wide
-            CA certificate store is used. Default value is set by I(OVIRT_CAFILE) environment variable."
-            - "C(kerberos) - A boolean flag indicating if Kerberos authentication
-            should be used instead of the default basic authentication."
-            - "C(headers) - Dictionary of HTTP headers to be added to each API call."
+        suboptions:
+            username:
+                description:
+                    - The name of the user, something like I(admin@internal).
+                    - Default value is set by I(OVIRT_USERNAME) environment variable.
+                required: true
+            password:
+                description:
+                    - The password of the user.
+                    - Default value is set by I(OVIRT_PASSWORD) environment variable.
path: lib/ansible/plugins/doc_fragments/ovirt.py
text: @user1:
We use `C(..) ` for code and environment variables. 

```suggestion
                    - Default value is set by C(OVIRT_PASSWORD) environment variable.
```

diff_hunk: @@ -30,25 +30,46 @@ class ModuleDocFragment(object):
     auth:
         description:
             - "Dictionary with values needed to create HTTP/HTTPS connection to oVirt:"
-            - C(username)[I(required)] - The name of the user, something like I(admin@internal).
-              Default value is set by I(OVIRT_USERNAME) environment variable.
-            - "C(password)[I(required)] - The password of the user. Default value is set by I(OVIRT_PASSWORD) environment variable."
-            - "C(url) - A string containing the API URL of the server, usually
-            something like `I(https://server.example.com/ovirt-engine/api)`. Default value is set by I(OVIRT_URL) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(hostname) - A string containing the hostname of the server, usually
-            something like `I(server.example.com)`. Default value is set by I(OVIRT_HOSTNAME) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(token) - Token to be used instead of login with username/password. Default value is set by I(OVIRT_TOKEN) environment variable."
-            - "C(insecure) - A boolean flag that indicates if the server TLS
-            certificate and host name should be checked."
-            - "C(ca_file) - A PEM file containing the trusted CA certificates. The
-            certificate presented by the server will be verified using these CA
-            certificates. If `C(ca_file)` parameter is not set, system wide
-            CA certificate store is used. Default value is set by I(OVIRT_CAFILE) environment variable."
-            - "C(kerberos) - A boolean flag indicating if Kerberos authentication
-            should be used instead of the default basic authentication."
-            - "C(headers) - Dictionary of HTTP headers to be added to each API call."
+        suboptions:
+            username:
+                description:
+                    - The name of the user, something like I(admin@internal).
+                    - Default value is set by I(OVIRT_USERNAME) environment variable.
+                required: true
+            password:
+                description:
+                    - The password of the user.
+                    - Default value is set by I(OVIRT_PASSWORD) environment variable.
+                required: true
+            url:
+                description:
+                    - A string containing the API URL of the server, usually something like `I(https://server.example.com/ovirt-engine/api)`.
+                    - Default value is set by I(OVIRT_URL) environment variable.
+                    - Either C(url) or C(hostname) is required.
+            hostname:
+                description:
+                    - A string containing the hostname of the server, usually something like `I(server.example.com)`.
+                    - Default value is set by I(OVIRT_HOSTNAME) environment variable.
+                    - Either C(url) or C(hostname) is required.
+            token:
+                description:
+                    - Token to be used instead of login with username/password.
+                    - Default value is set by I(OVIRT_TOKEN) environment variable.
+            insecure:
+                description:
+                    - A boolean flag that indicates if the server TLS certificate and host name should be checked.
+            ca_file:
+                description:
+                    - A PEM file containing the trusted CA certificates.
+                    - The certificate presented by the server will be verified using these CA certificates.
+                    - If `C(ca_file)` parameter is not set, system wide CA certificate store is used.
+                    - Default value is set by I(OVIRT_CAFILE) environment variable.
path: lib/ansible/plugins/doc_fragments/ovirt.py
text: @user1:
```suggestion
                    - Default value is set by C(OVIRT_CAFILE) environment variable.
```

diff_hunk: @@ -30,25 +30,46 @@ class ModuleDocFragment(object):
     auth:
         description:
             - "Dictionary with values needed to create HTTP/HTTPS connection to oVirt:"
-            - C(username)[I(required)] - The name of the user, something like I(admin@internal).
-              Default value is set by I(OVIRT_USERNAME) environment variable.
-            - "C(password)[I(required)] - The password of the user. Default value is set by I(OVIRT_PASSWORD) environment variable."
-            - "C(url) - A string containing the API URL of the server, usually
-            something like `I(https://server.example.com/ovirt-engine/api)`. Default value is set by I(OVIRT_URL) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(hostname) - A string containing the hostname of the server, usually
-            something like `I(server.example.com)`. Default value is set by I(OVIRT_HOSTNAME) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(token) - Token to be used instead of login with username/password. Default value is set by I(OVIRT_TOKEN) environment variable."
-            - "C(insecure) - A boolean flag that indicates if the server TLS
-            certificate and host name should be checked."
-            - "C(ca_file) - A PEM file containing the trusted CA certificates. The
-            certificate presented by the server will be verified using these CA
-            certificates. If `C(ca_file)` parameter is not set, system wide
-            CA certificate store is used. Default value is set by I(OVIRT_CAFILE) environment variable."
-            - "C(kerberos) - A boolean flag indicating if Kerberos authentication
-            should be used instead of the default basic authentication."
-            - "C(headers) - Dictionary of HTTP headers to be added to each API call."
+        suboptions:
+            username:
+                description:
+                    - The name of the user, something like I(admin@internal).
+                    - Default value is set by I(OVIRT_USERNAME) environment variable.
+                required: true
+            password:
+                description:
+                    - The password of the user.
+                    - Default value is set by I(OVIRT_PASSWORD) environment variable.
+                required: true
+            url:
+                description:
+                    - A string containing the API URL of the server, usually something like `I(https://server.example.com/ovirt-engine/api)`.
+                    - Default value is set by I(OVIRT_URL) environment variable.
path: lib/ansible/plugins/doc_fragments/ovirt.py
text: @user1:
```suggestion
                    - Default value is set by C(OVIRT_URL) environment variable.
```

diff_hunk: @@ -30,25 +30,46 @@ class ModuleDocFragment(object):
     auth:
         description:
             - "Dictionary with values needed to create HTTP/HTTPS connection to oVirt:"
-            - C(username)[I(required)] - The name of the user, something like I(admin@internal).
-              Default value is set by I(OVIRT_USERNAME) environment variable.
-            - "C(password)[I(required)] - The password of the user. Default value is set by I(OVIRT_PASSWORD) environment variable."
-            - "C(url) - A string containing the API URL of the server, usually
-            something like `I(https://server.example.com/ovirt-engine/api)`. Default value is set by I(OVIRT_URL) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(hostname) - A string containing the hostname of the server, usually
-            something like `I(server.example.com)`. Default value is set by I(OVIRT_HOSTNAME) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(token) - Token to be used instead of login with username/password. Default value is set by I(OVIRT_TOKEN) environment variable."
-            - "C(insecure) - A boolean flag that indicates if the server TLS
-            certificate and host name should be checked."
-            - "C(ca_file) - A PEM file containing the trusted CA certificates. The
-            certificate presented by the server will be verified using these CA
-            certificates. If `C(ca_file)` parameter is not set, system wide
-            CA certificate store is used. Default value is set by I(OVIRT_CAFILE) environment variable."
-            - "C(kerberos) - A boolean flag indicating if Kerberos authentication
-            should be used instead of the default basic authentication."
-            - "C(headers) - Dictionary of HTTP headers to be added to each API call."
+        suboptions:
+            username:
+                description:
+                    - The name of the user, something like I(admin@internal).
+                    - Default value is set by I(OVIRT_USERNAME) environment variable.
+                required: true
+            password:
+                description:
+                    - The password of the user.
+                    - Default value is set by I(OVIRT_PASSWORD) environment variable.
+                required: true
+            url:
+                description:
+                    - A string containing the API URL of the server, usually something like `I(https://server.example.com/ovirt-engine/api)`.
+                    - Default value is set by I(OVIRT_URL) environment variable.
+                    - Either C(url) or C(hostname) is required.
+            hostname:
+                description:
+                    - A string containing the hostname of the server, usually something like `I(server.example.com)`.
+                    - Default value is set by I(OVIRT_HOSTNAME) environment variable.
+                    - Either C(url) or C(hostname) is required.
+            token:
+                description:
+                    - Token to be used instead of login with username/password.
+                    - Default value is set by I(OVIRT_TOKEN) environment variable.
path: lib/ansible/plugins/doc_fragments/ovirt.py
text: @user1:
```suggestion
                    - Default value is set by C(OVIRT_TOKEN) environment variable.
```

diff_hunk: @@ -30,25 +30,46 @@ class ModuleDocFragment(object):
     auth:
         description:
             - "Dictionary with values needed to create HTTP/HTTPS connection to oVirt:"
-            - C(username)[I(required)] - The name of the user, something like I(admin@internal).
-              Default value is set by I(OVIRT_USERNAME) environment variable.
-            - "C(password)[I(required)] - The password of the user. Default value is set by I(OVIRT_PASSWORD) environment variable."
-            - "C(url) - A string containing the API URL of the server, usually
-            something like `I(https://server.example.com/ovirt-engine/api)`. Default value is set by I(OVIRT_URL) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(hostname) - A string containing the hostname of the server, usually
-            something like `I(server.example.com)`. Default value is set by I(OVIRT_HOSTNAME) environment variable.
-            Either C(url) or C(hostname) is required."
-            - "C(token) - Token to be used instead of login with username/password. Default value is set by I(OVIRT_TOKEN) environment variable."
-            - "C(insecure) - A boolean flag that indicates if the server TLS
-            certificate and host name should be checked."
-            - "C(ca_file) - A PEM file containing the trusted CA certificates. The
-            certificate presented by the server will be verified using these CA
-            certificates. If `C(ca_file)` parameter is not set, system wide
-            CA certificate store is used. Default value is set by I(OVIRT_CAFILE) environment variable."
-            - "C(kerberos) - A boolean flag indicating if Kerberos authentication
-            should be used instead of the default basic authentication."
-            - "C(headers) - Dictionary of HTTP headers to be added to each API call."
+        suboptions:
+            username:
+                description:
+                    - The name of the user, something like I(admin@internal).
+                    - Default value is set by I(OVIRT_USERNAME) environment variable.
+                required: true
+            password:
+                description:
+                    - The password of the user.
+                    - Default value is set by I(OVIRT_PASSWORD) environment variable.
+                required: true
+            url:
+                description:
+                    - A string containing the API URL of the server, usually something like `I(https://server.example.com/ovirt-engine/api)`.
+                    - Default value is set by I(OVIRT_URL) environment variable.
+                    - Either C(url) or C(hostname) is required.
+            hostname:
+                description:
+                    - A string containing the hostname of the server, usually something like `I(server.example.com)`.
+                    - Default value is set by I(OVIRT_HOSTNAME) environment variable.
+                    - Either C(url) or C(hostname) is required.
+            token:
+                description:
+                    - Token to be used instead of login with username/password.
+                    - Default value is set by I(OVIRT_TOKEN) environment variable.
+            insecure:
+                description:
+                    - A boolean flag that indicates if the server TLS certificate and host name should be checked.
+            ca_file:
+                description:
+                    - A PEM file containing the trusted CA certificates.
+                    - The certificate presented by the server will be verified using these CA certificates.
+                    - If `C(ca_file)` parameter is not set, system wide CA certificate store is used.
path: lib/ansible/plugins/doc_fragments/ovirt.py
text: @user1:
```suggestion
                    - If C(ca_file) parameter is not set, system wide CA certificate store is used.
```