[WIP] Use return doc fragments

antsibull-nox.toml

@@ -45,6 +45,7 @@ codeblocks_restrict_types = [
 codeblocks_restrict_type_exact_case = true
 codeblocks_allow_without_type = false
 codeblocks_allow_literal_blocks = false
+ansible_core_package = "https://github.com/ansible/ansible/archive/devel.tar.gz"
 
 [sessions.license_check]
 run_reuse = true

plugins/doc_fragments/_module_csr.py

@@ -341,3 +341,68 @@ class ModuleDocFragment:
   - plugin: community.crypto.parse_serial
     plugin_type: filter
 """
+
+    RETURN = r"""
+privatekey:
+  description:
+    - Path to the TLS/SSL private key the CSR was generated for.
+    - Will be V(none) if the private key has been provided in O(privatekey_content).
+  returned: changed or success
+  type: str
+  sample: /etc/ssl/private/ansible.com.pem
+subject:
+  description: A list of the subject tuples attached to the CSR.
+  returned: changed or success
+  type: list
+  elements: list
+  sample: [['CN', 'www.ansible.com'], ['O', 'Ansible']]
+subjectAltName:
+  description: The alternative names this CSR is valid for.
+  returned: changed or success
+  type: list
+  elements: str
+  sample: ['DNS:www.ansible.com', 'DNS:m.ansible.com']
+keyUsage:
+  description: Purpose for which the public key may be used.
+  returned: changed or success
+  type: list
+  elements: str
+  sample: ['digitalSignature', 'keyAgreement']
+extendedKeyUsage:
+  description: Additional restriction on the public key purposes.
+  returned: changed or success
+  type: list
+  elements: str
+  sample: ['clientAuth']
+basicConstraints:
+  description: Indicates if the certificate belongs to a CA.
+  returned: changed or success
+  type: list
+  elements: str
+  sample: ['CA:TRUE', 'pathLenConstraint:0']
+ocsp_must_staple:
+  description: Indicates whether the certificate has the OCSP Must Staple feature enabled.
+  returned: changed or success
+  type: bool
+  sample: false
+name_constraints_permitted:
+  description: List of permitted subtrees to sign certificates for.
+  returned: changed or success
+  type: list
+  elements: str
+  sample: ['email:.somedomain.com']
+name_constraints_excluded:
+  description: List of excluded subtrees the CA cannot sign certificates for.
+  returned: changed or success
+  type: list
+  elements: str
+  sample: ['email:.com']
+"""
+
+    # Private fragment only for community.crypto.csr!
+    _RETURN_CSR = r"""
+name_constraints_permitted:
+  version_added: 1.1.0
+name_constraints_excluded:
+  version_added: 1.1.0
+"""

plugins/doc_fragments/_module_privatekey.py

@@ -143,3 +143,33 @@ class ModuleDocFragment:
   - module: community.crypto.openssl_pkcs12
   - module: community.crypto.openssl_publickey
 """
+
+    RETURN = r"""
+size:
+  description: Size (in bits) of the TLS/SSL private key.
+  returned: changed or success
+  type: int
+  sample: 4096
+type:
+  description: Algorithm used to generate the TLS/SSL private key.
+  returned: changed or success
+  type: str
+  sample: RSA
+curve:
+  description: Elliptic curve used to generate the TLS/SSL private key.
+  returned: changed or success, and O(type) is V(ECC)
+  type: str
+  sample: secp256r1
+fingerprint:
+  description:
+    - The fingerprint of the public key. Fingerprint will be generated for each C(hashlib.algorithms) available.
+  returned: changed or success
+  type: dict
+  sample:
+    md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
+    sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
+    sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
+    sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
+    sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
+    sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
+"""

plugins/modules/openssl_csr.py

@@ -165,67 +165,11 @@
 """
 
 RETURN = r"""
-privatekey:
-  description:
-    - Path to the TLS/SSL private key the CSR was generated for.
-    - Will be V(none) if the private key has been provided in O(privatekey_content).
-  returned: changed or success
-  type: str
-  sample: /etc/ssl/private/ansible.com.pem
 filename:
   description: Path to the generated Certificate Signing Request.
   returned: changed or success
   type: str
   sample: /etc/ssl/csr/www.ansible.com.csr
-subject:
-  description: A list of the subject tuples attached to the CSR.
-  returned: changed or success
-  type: list
-  elements: list
-  sample: [['CN', 'www.ansible.com'], ['O', 'Ansible']]
-subjectAltName:
-  description: The alternative names this CSR is valid for.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['DNS:www.ansible.com', 'DNS:m.ansible.com']
-keyUsage:
-  description: Purpose for which the public key may be used.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['digitalSignature', 'keyAgreement']
-extendedKeyUsage:
-  description: Additional restriction on the public key purposes.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['clientAuth']
-basicConstraints:
-  description: Indicates if the certificate belongs to a CA.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['CA:TRUE', 'pathLenConstraint:0']
-ocsp_must_staple:
-  description: Indicates whether the certificate has the OCSP Must Staple feature enabled.
-  returned: changed or success
-  type: bool
-  sample: false
-name_constraints_permitted:
-  description: List of permitted subtrees to sign certificates for.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['email:.somedomain.com']
-  version_added: 1.1.0
-name_constraints_excluded:
-  description: List of excluded subtrees the CA cannot sign certificates for.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['email:.com']
-  version_added: 1.1.0
 backup_file:
   description: Name of backup file created.
   returned: changed and if O(backup) is V(true)
@@ -236,6 +180,10 @@
   returned: if O(state) is V(present) and O(return_content) is V(true)
   type: str
   version_added: "1.0.0"
+
+extends_documentation_fragment:
+  - community.crypto._module_csr
+  - community.crypto._module_csr._return_csr
 """
 
 import os

plugins/modules/openssl_csr_pipe.py

@@ -74,57 +74,13 @@
   returned: changed or success
   type: str
   sample: /etc/ssl/private/ansible.com.pem
-subject:
-  description: A list of the subject tuples attached to the CSR.
-  returned: changed or success
-  type: list
-  elements: list
-  sample: [['CN', 'www.ansible.com'], ['O', 'Ansible']]
-subjectAltName:
-  description: The alternative names this CSR is valid for.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['DNS:www.ansible.com', 'DNS:m.ansible.com']
-keyUsage:
-  description: Purpose for which the public key may be used.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['digitalSignature', 'keyAgreement']
-extendedKeyUsage:
-  description: Additional restriction on the public key purposes.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['clientAuth']
-basicConstraints:
-  description: Indicates if the certificate belongs to a CA.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['CA:TRUE', 'pathLenConstraint:0']
-ocsp_must_staple:
-  description: Indicates whether the certificate has the OCSP Must Staple feature enabled.
-  returned: changed or success
-  type: bool
-  sample: false
-name_constraints_permitted:
-  description: List of permitted subtrees to sign certificates for.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['email:.somedomain.com']
-name_constraints_excluded:
-  description: List of excluded subtrees the CA cannot sign certificates for.
-  returned: changed or success
-  type: list
-  elements: str
-  sample: ['email:.com']
 csr:
   description: The (current or generated) CSR's content.
   returned: changed or success
   type: str
+
+extends_documentation_fragment:
+  - community.crypto._module_csr
 """
 
 import typing as t

plugins/modules/openssl_privatekey.py

@@ -108,38 +108,11 @@
 """
 
 RETURN = r"""
-size:
-  description: Size (in bits) of the TLS/SSL private key.
-  returned: changed or success
-  type: int
-  sample: 4096
-type:
-  description: Algorithm used to generate the TLS/SSL private key.
-  returned: changed or success
-  type: str
-  sample: RSA
-curve:
-  description: Elliptic curve used to generate the TLS/SSL private key.
-  returned: changed or success, and O(type) is V(ECC)
-  type: str
-  sample: secp256r1
 filename:
   description: Path to the generated TLS/SSL private key file.
   returned: changed or success
   type: str
   sample: /etc/ssl/private/ansible.com.pem
-fingerprint:
-  description:
-    - The fingerprint of the public key. Fingerprint will be generated for each C(hashlib.algorithms) available.
-  returned: changed or success
-  type: dict
-  sample:
-    md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
-    sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
-    sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
-    sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
-    sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
-    sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
 backup_file:
   description: Name of backup file created.
   returned: changed and if O(backup) is V(true)
@@ -152,6 +125,9 @@
   returned: if O(state) is V(present) and O(return_content) is V(true)
   type: str
   version_added: '1.0.0'
+
+extends_documentation_fragment:
+  - community.crypto._module_privatekey
 """
 
 import os

plugins/modules/openssl_privatekey_pipe.py

@@ -116,33 +116,6 @@
 """
 
 RETURN = r"""
-size:
-  description: Size (in bits) of the TLS/SSL private key.
-  returned: changed or success
-  type: int
-  sample: 4096
-type:
-  description: Algorithm used to generate the TLS/SSL private key.
-  returned: changed or success
-  type: str
-  sample: RSA
-curve:
-  description: Elliptic curve used to generate the TLS/SSL private key.
-  returned: changed or success, and O(type) is V(ECC)
-  type: str
-  sample: secp256r1
-fingerprint:
-  description:
-    - The fingerprint of the public key. Fingerprint will be generated for each C(hashlib.algorithms) available.
-  returned: changed or success
-  type: dict
-  sample:
-    md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
-    sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
-    sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
-    sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
-    sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
-    sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
 privatekey:
   description:
     - The generated private key's content.
@@ -151,4 +124,7 @@
     - Will be Base64-encoded if the key is in raw format.
   returned: changed, or O(return_current_key) is V(true)
   type: str
+
+extends_documentation_fragment:
+  - community.crypto._module_privatekey
 """