Reformat documentation with 'andebox yaml-doc' (#828)

* Reformat documentation with 'andebox yaml-doc'. * Fix/improve. * Remaining fixes. * One more.
2026-05-07 05:43:06 +00:00 · 2024-12-28 17:00:28 +01:00
parent 2ed7f69b83
commit 942be86635
54 changed files with 5605 additions and 5968 deletions
--- a/plugins/modules/openssl_dhparam.py
+++ b/plugins/modules/openssl_dhparam.py
@@ -9,89 +9,85 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type


-DOCUMENTATION = r'''
---
+DOCUMENTATION = r"""
 module: openssl_dhparam
 short_description: Generate OpenSSL Diffie-Hellman Parameters
 description:
-    - This module allows one to (re)generate OpenSSL DH-params.
-    - This module uses file common arguments to specify generated file permissions.
-    - "Please note that the module regenerates existing DH params if they do not
-      match the module's options. If you are concerned that this could overwrite
-      your existing DH params, consider using the O(backup) option."
-    - The module can use the cryptography Python library, or the C(openssl) executable.
-      By default, it tries to detect which one is available. This can be overridden
-      with the O(select_crypto_backend) option.
+  - This module allows one to (re)generate OpenSSL DH-params.
+  - This module uses file common arguments to specify generated file permissions.
+  - Please note that the module regenerates existing DH params if they do not match the module's options. If you are concerned
+    that this could overwrite your existing DH params, consider using the O(backup) option.
+  - The module can use the cryptography Python library, or the C(openssl) executable. By default, it tries to detect which
+    one is available. This can be overridden with the O(select_crypto_backend) option.
 requirements:
-    - Either cryptography >= 2.0
-    - Or OpenSSL binary C(openssl)
+  - Either cryptography >= 2.0
+  - Or OpenSSL binary C(openssl)
 author:
-    - Thom Wiggers (@thomwiggers)
+  - Thom Wiggers (@thomwiggers)
 extends_documentation_fragment:
-    - ansible.builtin.files
-    - community.crypto.attributes
-    - community.crypto.attributes.files
+  - ansible.builtin.files
+  - community.crypto.attributes
+  - community.crypto.attributes.files
 attributes:
-    check_mode:
-        support: full
-    diff_mode:
-        support: none
-    safe_file_operations:
-        support: full
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+  safe_file_operations:
+    support: full
 options:
-    state:
-        description:
-            - Whether the parameters should exist or not,
-              taking action if the state is different from what is stated.
-        type: str
-        default: present
-        choices: [ absent, present ]
-    size:
-        description:
-            - Size (in bits) of the generated DH-params.
-        type: int
-        default: 4096
-    force:
-        description:
-            - Should the parameters be regenerated even it it already exists.
-        type: bool
-        default: false
-    path:
-        description:
-            - Name of the file in which the generated parameters will be saved.
-        type: path
-        required: true
-    backup:
-        description:
-            - Create a backup file including a timestamp so you can get the original
-              DH params back if you overwrote them with new ones by accident.
-        type: bool
-        default: false
-    select_crypto_backend:
-        description:
-            - Determines which crypto backend to use.
-            - The default choice is V(auto), which tries to use C(cryptography) if available, and falls back to C(openssl).
-            - If set to V(openssl), will try to use the OpenSSL C(openssl) executable.
-            - If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
-        type: str
-        default: auto
-        choices: [ auto, cryptography, openssl ]
-        version_added: "1.0.0"
-    return_content:
-        description:
-            - If set to V(true), will return the (current or generated) DH parameter's content as RV(dhparams).
-        type: bool
-        default: false
-        version_added: "1.0.0"
+  state:
+    description:
+      - Whether the parameters should exist or not, taking action if the state is different from what is stated.
+    type: str
+    default: present
+    choices: [absent, present]
+  size:
+    description:
+      - Size (in bits) of the generated DH-params.
+    type: int
+    default: 4096
+  force:
+    description:
+      - Should the parameters be regenerated even it it already exists.
+    type: bool
+    default: false
+  path:
+    description:
+      - Name of the file in which the generated parameters will be saved.
+    type: path
+    required: true
+  backup:
+    description:
+      - Create a backup file including a timestamp so you can get the original DH params back if you overwrote them with new
+        ones by accident.
+    type: bool
+    default: false
+  select_crypto_backend:
+    description:
+      - Determines which crypto backend to use.
+      - The default choice is V(auto), which tries to use C(cryptography) if available, and falls back to C(openssl).
+      - If set to V(openssl), will try to use the OpenSSL C(openssl) executable.
+      - If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+    type: str
+    default: auto
+    choices: [auto, cryptography, openssl]
+    version_added: "1.0.0"
+  return_content:
+    description:
+      - If set to V(true), will return the (current or generated) DH parameter's content as RV(dhparams).
+    type: bool
+    default: false
+    version_added: "1.0.0"
 seealso:
-    - module: community.crypto.x509_certificate
-    - module: community.crypto.openssl_csr
-    - module: community.crypto.openssl_pkcs12
-    - module: community.crypto.openssl_privatekey
-    - module: community.crypto.openssl_publickey
-'''
+  - module: community.crypto.x509_certificate
+  - module: community.crypto.openssl_csr
+  - module: community.crypto.openssl_pkcs12
+  - module: community.crypto.openssl_privatekey
+  - module: community.crypto.openssl_publickey
+"""

-EXAMPLES = r'''
+EXAMPLES = r"""
 - name: Generate Diffie-Hellman parameters with the default size (4096 bits)
  community.crypto.openssl_dhparam:
    path: /etc/ssl/dhparams.pem
@@ -105,30 +101,30 @@ EXAMPLES = r'''
  community.crypto.openssl_dhparam:
    path: /etc/ssl/dhparams.pem
    force: true
-'''
+"""

-RETURN = r'''
+RETURN = r"""
 size:
-    description: Size (in bits) of the Diffie-Hellman parameters.
-    returned: changed or success
-    type: int
-    sample: 4096
+  description: Size (in bits) of the Diffie-Hellman parameters.
+  returned: changed or success
+  type: int
+  sample: 4096
 filename:
-    description: Path to the generated Diffie-Hellman parameters.
-    returned: changed or success
-    type: str
-    sample: /etc/ssl/dhparams.pem
+  description: Path to the generated Diffie-Hellman parameters.
+  returned: changed or success
+  type: str
+  sample: /etc/ssl/dhparams.pem
 backup_file:
-    description: Name of backup file created.
-    returned: changed and if O(backup) is V(true)
-    type: str
-    sample: /path/to/dhparams.pem.2019-03-09@11:22~
+  description: Name of backup file created.
+  returned: changed and if O(backup) is V(true)
+  type: str
+  sample: /path/to/dhparams.pem.2019-03-09@11:22~
 dhparams:
-    description: The (current or generated) DH params' content.
-    returned: if O(state) is V(present) and O(return_content) is V(true)
-    type: str
-    version_added: "1.0.0"
-'''
+  description: The (current or generated) DH params' content.
+  returned: if O(state) is V(present) and O(return_content) is V(true)
+  type: str
+  version_added: "1.0.0"
+"""

 import abc
 import os