Documentation: fix modules formatting (#161)

* Documentation: fix modules formatting

* Apply suggestions from code review

* Fix sanity

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

plugins/modules/openssh_keypair.py

@@ -12,7 +12,7 @@ DOCUMENTATION = '''
 ---
 module: openssh_keypair
 author: "David Kainz (@lolcube)"
-short_description: Generate OpenSSH private and public keys.
+short_description: Generate OpenSSH private and public keys
 description:
     - "This module allows one to (re)generate OpenSSH private and public keys. It uses
       ssh-keygen to generate keys. One can generate C(rsa), C(dsa), C(rsa1), C(ed25519)
@@ -59,7 +59,7 @@ options:
         description:
             - Allows to configure in which situations the module is allowed to regenerate private keys.
               The module will always generate a new key if the destination file does not exist.
-            - By default, the key will be regenerated when it doesn't match the module's options,
+            - By default, the key will be regenerated when it does not match the module's options,
               except when the key cannot be read or the passphrase does not match. Please note that
               this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior was as if C(full_idempotence)
               is specified.
@@ -91,6 +91,7 @@ options:
 notes:
     - In case the ssh key is broken or password protected, the module will fail.
       Set the I(force) option to C(yes) if you want to regenerate the keypair.
+    - Supports C(check_mode).
 
 extends_documentation_fragment: files
 '''
@@ -118,17 +119,17 @@ EXAMPLES = '''
 
 RETURN = '''
 size:
-    description: Size (in bits) of the SSH private key
+    description: Size (in bits) of the SSH private key.
     returned: changed or success
     type: int
     sample: 4096
 type:
-    description: Algorithm used to generate the SSH private key
+    description: Algorithm used to generate the SSH private key.
     returned: changed or success
     type: str
     sample: rsa
 filename:
-    description: Path to the generated SSH private key file
+    description: Path to the generated SSH private key file.
     returned: changed or success
     type: str
     sample: /tmp/id_ssh_rsa
@@ -138,12 +139,12 @@ fingerprint:
     type: str
     sample: SHA256:r4YCZxihVjedH2OlfjVGI6Y5xAYtdCwk8VxKyzVyYfM
 public_key:
-    description: The public key of the generated SSH private key
+    description: The public key of the generated SSH private key.
     returned: changed or success
     type: str
     sample: ssh-rsa AAAAB3Nza(...omitted...)veL4E3Xcw== test_key
 comment:
-    description: The comment of the generated key
+    description: The comment of the generated key.
     returned: changed or success
     type: str
     sample: test@comment

plugins/modules/openssl_dhparam.py

@@ -15,7 +15,7 @@ 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 don't
+    - "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 I(backup) option."
     - The module can use the cryptography Python library, or the C(openssl) executable.
@@ -71,6 +71,8 @@ options:
         type: bool
         default: no
         version_added: "1.0.0"
+notes:
+- Supports C(check_mode).
 extends_documentation_fragment:
 - files
 seealso:

plugins/modules/openssl_privatekey_info.py

@@ -65,6 +65,9 @@ options:
         default: auto
         choices: [ auto, cryptography, pyopenssl ]
 
+notes:
+- Supports C(check_mode).
+
 seealso:
 - module: community.crypto.openssl_privatekey
 - module: community.crypto.openssl_privatekey_pipe
@@ -81,28 +84,28 @@ EXAMPLES = r'''
   register: result
 
 - name: Dump information
-  debug:
+  ansible.builtin.debug:
     var: result
 '''
 
 RETURN = r'''
 can_load_key:
-    description: Whether the module was able to load the private key from disk
+    description: Whether the module was able to load the private key from disk.
     returned: always
     type: bool
 can_parse_key:
-    description: Whether the module was able to parse the private key
+    description: Whether the module was able to parse the private key.
     returned: always
     type: bool
 key_is_consistent:
     description:
         - Whether the key is consistent. Can also return C(none) next to C(yes) and
-          C(no), to indicate that consistency couldn't be checked.
+          C(no), to indicate that consistency could not be checked.
         - In case the check returns C(no), the module will fail.
     returned: always
     type: bool
 public_key:
-    description: Private key's public key in PEM format
+    description: Private key's public key in PEM format.
     returned: success
     type: str
     sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."

plugins/modules/openssl_signature_info.py

@@ -14,7 +14,7 @@ module: openssl_signature_info
 version_added: 1.1.0
 short_description: Verify signatures with openssl
 description:
-    - This module allows one to verify a signature for a file via a certificate.
+    - This module allows one to verify a signature for a file by a certificate.
     - The module can use the cryptography Python library, or the pyOpenSSL Python
       library. By default, it tries to detect which one is available. This can be
       overridden with the I(select_crypto_backend) option. Please note that the PyOpenSSL backend
@@ -61,6 +61,7 @@ notes:
       RSA keys: C(cryptography) >= 1.4
       DSA and ECDSA keys: C(cryptography) >= 1.5
       ed448 and ed25519 keys: C(cryptography) >= 2.6
+    - Supports C(check_mode).
 seealso:
     - module: community.crypto.openssl_signature
     - module: community.crypto.x509_certificate
@@ -88,7 +89,7 @@ EXAMPLES = r'''
 
 RETURN = r'''
 valid:
-    description: C(true) means the signature was valid for the given file, C(false) means it wasn't.
+    description: C(true) means the signature was valid for the given file, C(false) means it was not.
     returned: success
     type: bool
 '''

plugins/modules/x509_certificate.py

@@ -16,7 +16,7 @@ short_description: Generate and/or check OpenSSL certificates
 description:
     - It implements a notion of provider (ie. C(selfsigned), C(ownca), C(acme), C(assertonly), C(entrust))
       for your certificate.
-    - "Please note that the module regenerates existing certificate if it doesn't match the module's
+    - "Please note that the module regenerates existing certificate if it does not match the module's
       options, or if it seems to be corrupt. If you are concerned that this could overwrite
       your existing certificate, consider using the I(backup) option."
     - Note that this module was called C(openssl_certificate) when included directly in Ansible up to version 2.9.
@@ -86,6 +86,9 @@ options:
     ownca_privatekey_content:
         version_added: '1.0.0'
 
+notes:
+- Supports C(check_mode).
+
 seealso:
 - module: community.crypto.x509_certificate_pipe
 
@@ -150,8 +153,8 @@ EXAMPLES = r'''
 # The following example shows one assertonly usage using all existing options for
 # assertonly, and shows how to emulate the behavior with the x509_certificate_info,
 # openssl_csr_info, openssl_privatekey_info and assert modules:
-
+- name: Usage of assertonly with all existing options
-- community.crypto.x509_certificate:
+  community.crypto.x509_certificate:
     provider: assertonly
     path: /etc/ssl/crt/ansible.com.crt
     csr_path: /etc/ssl/csr/ansible.com.csr
@@ -182,7 +185,8 @@ EXAMPLES = r'''
     invalid_at: 20200331202428Z
     valid_in: 10  # in ten seconds
 
-- community.crypto.x509_certificate_info:
+- name: Get certificate information
+  community.crypto.x509_certificate_info:
     path: /etc/ssl/crt/ansible.com.crt
     # for valid_at, invalid_at and valid_in
     valid_at:
@@ -191,12 +195,14 @@ EXAMPLES = r'''
       ten_seconds: "+10"
   register: result
 
-- community.crypto.openssl_csr_info:
+- name: Get CSR information
+  community.crypto.openssl_csr_info:
     # Verifies that the CSR signature is valid; module will fail if not
     path: /etc/ssl/csr/ansible.com.csr
   register: result_csr
 
-- community.crypto.openssl_privatekey_info:
+- name: Get private key information
+  community.crypto.openssl_privatekey_info:
     path: /etc/ssl/csr/ansible.com.key
   register: result_privatekey
 

plugins/modules/x509_certificate_info.py

@@ -54,7 +54,7 @@ options:
             - Time can be specified either as relative time or as absolute timestamp.
             - Time will always be interpreted as UTC.
             - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
-              + C([w | d | h | m | s]) (e.g. C(+32w1d2h), and ASN.1 TIME (i.e. pattern C(YYYYMMDDHHMMSSZ)).
+              + C([w | d | h | m | s]) (e.g. C(+32w1d2h), and ASN.1 TIME (in other words, pattern C(YYYYMMDDHHMMSSZ)).
               Note that all timestamps will be treated as being in UTC.
         type: dict
     select_crypto_backend:
@@ -70,8 +70,9 @@ options:
         choices: [ auto, cryptography, pyopenssl ]
 
 notes:
-    - All timestamp values are provided in ASN.1 TIME format, i.e. following the C(YYYYMMDDHHMMSSZ) pattern.
+    - All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern.
       They are all in UTC.
+    - Supports C(check_mode).
 seealso:
 - module: community.crypto.x509_certificate
 - module: community.crypto.x509_certificate_pipe
@@ -94,7 +95,7 @@ EXAMPLES = r'''
   register: result
 
 - name: Dump information
-  debug:
+  ansible.builtin.debug:
     var: result
 
 
@@ -120,7 +121,7 @@ EXAMPLES = r'''
 
 RETURN = r'''
 expired:
-    description: Whether the certificate is expired (i.e. C(notAfter) is in the past)
+    description: Whether the certificate is expired (in other words, C(notAfter) is in the past).
     returned: success
     type: bool
 basic_constraints:
@@ -144,7 +145,7 @@ extended_key_usage_critical:
     returned: success
     type: bool
 extensions_by_oid:
-    description: Returns a dictionary for every extension OID
+    description: Returns a dictionary for every extension OID.
     returned: success
     type: dict
     contains:
@@ -153,7 +154,7 @@ extensions_by_oid:
             returned: success
             type: bool
         value:
-            description: The Base64 encoded value (in DER format) of the extension
+            description: The Base64 encoded value (in DER format) of the extension.
             returned: success
             type: str
             sample: "MAMCAQU="
@@ -212,17 +213,17 @@ subject_ordered:
     elements: list
     sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]'
 not_after:
-    description: C(notAfter) date as ASN.1 TIME
+    description: C(notAfter) date as ASN.1 TIME.
     returned: success
     type: str
     sample: 20190413202428Z
 not_before:
-    description: C(notBefore) date as ASN.1 TIME
+    description: C(notBefore) date as ASN.1 TIME.
     returned: success
     type: str
     sample: 20190331202428Z
 public_key:
-    description: Certificate's public key in PEM format
+    description: Certificate's public key in PEM format.
     returned: success
     type: str
     sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."

plugins/modules/x509_certificate_pipe.py

@@ -18,7 +18,7 @@ version_added: 1.3.0
 description:
     - It implements a notion of provider (ie. C(selfsigned), C(ownca), C(entrust))
       for your certificate.
-    - "Please note that the module regenerates an existing certificate if it doesn't match the module's
+    - "Please note that the module regenerates an existing certificate if it does not match the module's
       options, or if it seems to be corrupt. If you are concerned that this could overwrite
       your existing certificate, consider using the I(backup) option."
 author:
@@ -43,6 +43,9 @@ options:
 seealso:
 - module: community.crypto.x509_certificate
 
+notes:
+- Supports C(check_mode).
+
 extends_documentation_fragment:
     - community.crypto.module_certificate
     - community.crypto.module_certificate.backend_entrust_documentation
@@ -57,7 +60,8 @@ EXAMPLES = r'''
     privatekey_path: /etc/ssl/private/ansible.com.pem
     csr_path: /etc/ssl/csr/ansible.com.csr
   register: result
-- ansible.builtin.debug:
+- name: Print the certificate
+  ansible.builtin.debug:
     var: result.certificate
 
 # In the following example, both CSR and certificate file are stored on the

plugins/modules/x509_crl.py

@@ -15,7 +15,7 @@ version_added: '1.0.0'
 short_description: Generate Certificate Revocation Lists (CRLs)
 description:
     - This module allows one to (re)generate or update Certificate Revocation Lists (CRLs).
-    - Certificates on the revocation list can be either specified via serial number and (optionally) their issuer,
+    - Certificates on the revocation list can be either specified by serial number and (optionally) their issuer,
       or as a path to a certificate file in PEM format.
 requirements:
     - cryptography >= 1.2
@@ -233,6 +233,7 @@ extends_documentation_fragment:
 notes:
     - All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
     - Date specified should be UTC. Minutes and seconds are mandatory.
+    - Supports C(check_mode).
 '''
 
 EXAMPLES = r'''
@@ -259,7 +260,7 @@ EXAMPLES = r'''
 
 RETURN = r'''
 filename:
-    description: Path to the generated CRL
+    description: Path to the generated CRL.
     returned: changed or success
     type: str
     sample: /path/to/my-ca.crl
@@ -269,7 +270,7 @@ backup_file:
     type: str
     sample: /path/to/my-ca.crl.2019-03-09@11:22~
 privatekey:
-    description: Path to the private CA key
+    description: Path to the private CA key.
     returned: changed or success
     type: str
     sample: /path/to/my-ca.pem

plugins/modules/x509_crl_info.py

@@ -32,8 +32,9 @@ options:
         type: str
 
 notes:
-    - All timestamp values are provided in ASN.1 TIME format, i.e. following the C(YYYYMMDDHHMMSSZ) pattern.
+    - All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern.
       They are all in UTC.
+    - Supports C(check_mode).
 seealso:
     - module: community.crypto.x509_crl
 '''
@@ -44,7 +45,8 @@ EXAMPLES = r'''
     path: /etc/ssl/my-ca.crl
   register: result
 
-- debug:
+- name: Print the information
+  ansible.builtin.debug:
     msg: "{{ result }}"
 '''