diff options
author | Felix Fontein <felix@fontein.de> | 2019-10-15 17:07:10 +0200 |
---|---|---|
committer | Toshio Kuratomi <a.badger@gmail.com> | 2019-10-15 08:07:10 -0700 |
commit | cfcee2d069c667d5a43ab81bfa832c7aeb1e2c57 (patch) | |
tree | ba57da8a5558756c9174d8ff074df61d0e139440 | |
parent | b6259832dd608f9013393582de9a7648d4008e10 (diff) | |
download | ansible-cfcee2d069c667d5a43ab81bfa832c7aeb1e2c57.tar.gz |
[2.9] crypto modules: improve return value list documentation (#63409)
* crypto modules: improve return value list documentation (#62929)
* Improve return value documentation by allowing entry for return values.
* Add docs formatting, adjust styling.
* Fix sample return value. (Taken from https://tools.ietf.org/html/rfc7517#appendix-A.1.)
* Work around abuse of .
(cherry picked from commit 054285c34ce05ce0f28626e7f5d1964b93aa4c0d)
* Add changelog.
11 files changed, 62 insertions, 15 deletions
diff --git a/changelogs/fragments/62929-module-return-value-elements.yml b/changelogs/fragments/62929-module-return-value-elements.yml new file mode 100644 index 0000000000..884a0f34d8 --- /dev/null +++ b/changelogs/fragments/62929-module-return-value-elements.yml @@ -0,0 +1,2 @@ +minor_changes: +- "ansible-test - module validation now allows ``elements:`` for return value documentation." diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index d8ea4800ed..0d974f2cca 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -288,7 +288,10 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a {% endfor %} <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@" colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@"> <b>@{ key }@</b> - <div style="font-size: small; color: purple">@{ value.type | documented_type }@</div> + <div style="font-size: small"> + <span style="color: purple">@{ value.type | documented_type }@</span> + {% if value.elements %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %} + </div> {% if value.version_added %}<div style="font-style: italic; font-size: small; color: darkgreen">added in @{value.version_added}@</div>{% endif %} </td> <td>@{ value.returned | html_ify }@</td> @@ -360,7 +363,10 @@ Common return values are documented :ref:`here <common_return_values>`, the foll {% endfor %} <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@"> <b>@{ key }@</b> - <div style="font-size: small; color: purple">@{ value.type | documented_type }@</div> + <div style="font-size: small"> + <span style="color: purple">@{ value.type | documented_type }@</span> + {% if value.elements %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %} + </div> {% if value.version_added %}<div style="font-style: italic; font-size: small; color: darkgreen">added in @{value.version_added}@</div>{% endif %} </td> <td>@{ value.returned | html_ify }@</td> diff --git a/lib/ansible/modules/crypto/acme/acme_account_info.py b/lib/ansible/modules/crypto/acme/acme_account_info.py index 67a623d36f..cb2c78ec8d 100644 --- a/lib/ansible/modules/crypto/acme/acme_account_info.py +++ b/lib/ansible/modules/crypto/acme/acme_account_info.py @@ -91,12 +91,13 @@ account_uri: account: description: The account information, as retrieved from the ACME server. returned: if account exists - type: complex + type: dict contains: contact: description: the challenge resource that must be created for validation returned: always type: list + elements: str sample: "['mailto:me@example.com', 'tel:00123456789']" status: description: the account's status @@ -116,7 +117,7 @@ account: description: the public account key as a L(JSON Web Key,https://tools.ietf.org/html/rfc7517). returned: always type: str - sample: https://example.ca/account/1/orders + sample: '{"kty":"EC","crv":"P-256","x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4","y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"}' orders: description: @@ -124,6 +125,7 @@ orders: - "If I(retrieve_orders) is C(url_list), this will be a list of URLs." - "If I(retrieve_orders) is C(object_list), this will be a list of objects." type: list + #elements: ... depends on retrieve_orders returned: if account exists, I(retrieve_orders) is not C(ignore), and server supports order listing contains: status: @@ -146,6 +148,7 @@ orders: description: - List of identifiers this order is for. type: list + elements: dict contains: type: description: Type of identifier. C(dns) or C(ip). @@ -176,12 +179,13 @@ orders: description: - In case an error occurred during processing, this contains information about the error. - The field is structured as a problem document (RFC7807). - type: complex + type: dict returned: when an error occurred authorizations: description: - A list of URLs for authorizations for this order. type: list + elements: str finalize: description: - A URL used for finalizing an ACME order. diff --git a/lib/ansible/modules/crypto/acme/acme_certificate.py b/lib/ansible/modules/crypto/acme/acme_certificate.py index 52546aadac..2f2da8bc02 100644 --- a/lib/ansible/modules/crypto/acme/acme_certificate.py +++ b/lib/ansible/modules/crypto/acme/acme_certificate.py @@ -324,7 +324,8 @@ challenge_data: - Per identifier / challenge type challenge data. - Since Ansible 2.8.5, only challenges which are not yet valid are returned. returned: changed - type: complex + type: list + elements: dict contains: resource: description: The challenge resource that must be created for validation. @@ -366,14 +367,12 @@ challenge_data_dns: type: dict version_added: "2.5" authorizations: - description: ACME authorization data. + description: + - ACME authorization data. + - Maps an identifier to ACME authorization objects. See U(https://tools.ietf.org/html/rfc8555#section-7.1.4). returned: changed - type: complex - contains: - authorization: - description: ACME authorization object. See U(https://tools.ietf.org/html/rfc8555#section-7.1.4) - returned: success - type: dict + type: dict + sample: '{"example.com":{...}}' order_uri: description: ACME order URI. returned: changed @@ -397,6 +396,7 @@ all_chains: - See L(Section 7.4.2 of RFC8555,https://tools.ietf.org/html/rfc8555#section-7.4.2) for details. returned: when certificate was retrieved and I(retrieve_all_alternates) is set to C(yes) type: list + elements: dict contains: cert: description: diff --git a/lib/ansible/modules/crypto/certificate_complete_chain.py b/lib/ansible/modules/crypto/certificate_complete_chain.py index d418d342b3..77fbe2ee52 100644 --- a/lib/ansible/modules/crypto/certificate_complete_chain.py +++ b/lib/ansible/modules/crypto/certificate_complete_chain.py @@ -114,12 +114,14 @@ chain: - "Returned as a list of PEM certificates." returned: success type: list + elements: str complete_chain: description: - "The completed chain, including leaf, all intermediates, and root." - "Returned as a list of PEM certificates." returned: success type: list + elements: str ''' import os diff --git a/lib/ansible/modules/crypto/get_certificate.py b/lib/ansible/modules/crypto/get_certificate.py index 99883366a4..3aed838d68 100644 --- a/lib/ansible/modules/crypto/get_certificate.py +++ b/lib/ansible/modules/crypto/get_certificate.py @@ -86,6 +86,20 @@ extensions: description: Extensions applied to the cert returned: success type: list + elements: dict + contains: + critical: + returned: success + type: bool + description: Whether the extension is critical. + asn1_data: + returned: success + type: str + description: The Base64 encoded ASN.1 content of the extnesion. + name: + returned: success + type: str + description: The extension's name. issuer: description: Information about the issuer of the cert returned: success diff --git a/lib/ansible/modules/crypto/openssh_cert.py b/lib/ansible/modules/crypto/openssh_cert.py index 3bf2211076..44848449ec 100644 --- a/lib/ansible/modules/crypto/openssh_cert.py +++ b/lib/ansible/modules/crypto/openssh_cert.py @@ -193,6 +193,7 @@ info: description: Information about the certificate. Output of C(ssh-keygen -L -f). returned: change or success type: list + elements: str ''' diff --git a/lib/ansible/modules/crypto/openssl_certificate_info.py b/lib/ansible/modules/crypto/openssl_certificate_info.py index 9ef343e206..7fa82e354a 100644 --- a/lib/ansible/modules/crypto/openssl_certificate_info.py +++ b/lib/ansible/modules/crypto/openssl_certificate_info.py @@ -116,6 +116,7 @@ basic_constraints: description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[CA:TRUE, pathlen:1]" basic_constraints_critical: description: Whether the C(basic_constraints) extension is critical. @@ -125,6 +126,7 @@ extended_key_usage: description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[Biometric Info, DVCS, Time Stamping]" extended_key_usage_critical: description: Whether the C(extended_key_usage) extension is critical. @@ -133,7 +135,7 @@ extended_key_usage_critical: extensions_by_oid: description: Returns a dictionary for every extension OID returned: success - type: complex + type: dict contains: critical: description: Whether the extension is critical. @@ -158,6 +160,7 @@ subject_alt_name: description: Entries in the C(subject_alt_name) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" subject_alt_name_critical: description: Whether the C(subject_alt_name) extension is critical. @@ -182,6 +185,7 @@ issuer_ordered: description: The certificate's issuer as an ordered list of tuples. returned: success type: list + elements: list sample: '[["organizationName", "Ansible"], ["commonName": "ca.example.com"]]' version_added: "2.9" subject: @@ -195,6 +199,7 @@ subject_ordered: description: The certificate's subject as an ordered list of tuples. returned: success type: list + elements: list sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]' version_added: "2.9" not_after: @@ -265,6 +270,7 @@ authority_cert_issuer: - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present. returned: success and if the pyOpenSSL backend is I(not) used type: list + elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" version_added: "2.9" authority_cert_serial_number: diff --git a/lib/ansible/modules/crypto/openssl_csr.py b/lib/ansible/modules/crypto/openssl_csr.py index a6266e68a2..84fbaa9cac 100644 --- a/lib/ansible/modules/crypto/openssl_csr.py +++ b/lib/ansible/modules/crypto/openssl_csr.py @@ -365,26 +365,31 @@ 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 diff --git a/lib/ansible/modules/crypto/openssl_csr_info.py b/lib/ansible/modules/crypto/openssl_csr_info.py index 60ecc52395..cb80b55b01 100644 --- a/lib/ansible/modules/crypto/openssl_csr_info.py +++ b/lib/ansible/modules/crypto/openssl_csr_info.py @@ -82,6 +82,7 @@ basic_constraints: description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[CA:TRUE, pathlen:1]" basic_constraints_critical: description: Whether the C(basic_constraints) extension is critical. @@ -91,6 +92,7 @@ extended_key_usage: description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[Biometric Info, DVCS, Time Stamping]" extended_key_usage_critical: description: Whether the C(extended_key_usage) extension is critical. @@ -99,7 +101,7 @@ extended_key_usage_critical: extensions_by_oid: description: Returns a dictionary for every extension OID returned: success - type: complex + type: dict contains: critical: description: Whether the extension is critical. @@ -124,6 +126,7 @@ subject_alt_name: description: Entries in the C(subject_alt_name) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" subject_alt_name_critical: description: Whether the C(subject_alt_name) extension is critical. @@ -148,6 +151,7 @@ subject_ordered: description: The CSR's subject as an ordered list of tuples. returned: success type: list + elements: list sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]' version_added: "2.9" public_key: @@ -187,6 +191,7 @@ authority_cert_issuer: - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present. returned: success and if the pyOpenSSL backend is I(not) used type: list + elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" version_added: "2.9" authority_cert_serial_number: diff --git a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py index 1b9848d8d1..d6b9c5c84f 100644 --- a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py +++ b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py @@ -142,6 +142,8 @@ return_schema = Any( 'sample': Any(None, list, dict, int, float, *string_types), 'example': Any(None, list, dict, int, float, *string_types), 'contains': object, + # in case of type='list' elements define type of individual item in list + 'elements': Any(None, 'bits', 'bool', 'bytes', 'dict', 'float', 'int', 'json', 'jsonarg', 'list', 'path', 'raw', 'sid', 'str'), } } ), |