From cc45650e82b769125eb4f6dad5cb5de330be4501 Mon Sep 17 00:00:00 2001
From: Toshio Kuratomi <a.badger@gmail.com>
Date: Wed, 17 Jun 2020 01:29:18 -0700
Subject: [PATCH] Use fqcn for modules listed in M() and seealso. (#72)

---
 plugins/modules/acme_account.py               | 12 +++----
 plugins/modules/acme_account_info.py          |  5 +--
 plugins/modules/acme_certificate.py           | 26 +++++++-------
 plugins/modules/acme_certificate_revoke.py    |  2 +-
 plugins/modules/acme_challenge_cert_helper.py |  5 +--
 plugins/modules/acme_inspect.py               |  4 +--
 plugins/modules/certificate_complete_chain.py |  2 +-
 plugins/modules/ecs_certificate.py            |  4 +--
 plugins/modules/ecs_domain.py                 |  4 +--
 plugins/modules/openssl_csr.py                | 10 +++---
 plugins/modules/openssl_csr_info.py           |  2 +-
 plugins/modules/openssl_dhparam.py            | 10 +++---
 plugins/modules/openssl_pkcs12.py             | 10 +++---
 plugins/modules/openssl_privatekey.py         | 10 +++---
 plugins/modules/openssl_privatekey_info.py    |  2 +-
 plugins/modules/openssl_publickey.py          | 10 +++---
 plugins/modules/x509_certificate.py           | 35 +++++++++++--------
 plugins/modules/x509_certificate_info.py      | 12 ++++---
 plugins/modules/x509_crl_info.py              |  2 +-
 19 files changed, 88 insertions(+), 79 deletions(-)

diff --git a/plugins/modules/acme_account.py b/plugins/modules/acme_account.py
index e5b3303a..9cffc4a0 100644
--- a/plugins/modules/acme_account.py
+++ b/plugins/modules/acme_account.py
@@ -19,19 +19,19 @@ description:
       such as L(Let's Encrypt,https://letsencrypt.org/)."
    - "This module only works with the ACME v2 protocol."
 notes:
-   - "The M(acme_certificate) module also allows to do basic account management.
+   - "The M(community.crypto.acme_certificate) module also allows to do basic account management.
       When using both modules, it is recommended to disable account management
-      for M(acme_certificate). For that, use the C(modify_account) option of
-      M(acme_certificate)."
+      for M(community.crypto.acme_certificate). For that, use the C(modify_account) option of
+      M(community.crypto.acme_certificate)."
 seealso:
   - name: Automatic Certificate Management Environment (ACME)
     description: The specification of the ACME protocol (RFC 8555).
     link: https://tools.ietf.org/html/rfc8555
-  - module: acme_account_info
+  - module: community.crypto.acme_account_info
     description: Retrieves facts about an ACME account.
-  - module: openssl_privatekey
+  - module: community.crypto.openssl_privatekey
     description: Can be used to create a private account key.
-  - module: acme_inspect
+  - module: community.crypto.acme_inspect
     description: Allows to debug problems.
 extends_documentation_fragment:
 - community.crypto.acme
diff --git a/plugins/modules/acme_account_info.py b/plugins/modules/acme_account_info.py
index bb21acfd..f547d509 100644
--- a/plugins/modules/acme_account_info.py
+++ b/plugins/modules/acme_account_info.py
@@ -19,7 +19,8 @@ description:
       such as L(Let's Encrypt,https://letsencrypt.org/)."
    - "This module only works with the ACME v2 protocol."
 notes:
-   - "The M(acme_account) module allows to modify, create and delete ACME accounts."
+   - "The M(community.crypto.acme_account) module allows to modify, create and delete ACME
+      accounts."
    - "This module was called C(acme_account_facts) before Ansible 2.8. The usage
       did not change."
 options:
@@ -37,7 +38,7 @@ options:
       - object_list
     default: ignore
 seealso:
-  - module: acme_account
+  - module: community.crypto.acme_account
     description: Allows to create, modify or delete an ACME account.
 extends_documentation_fragment:
 - community.crypto.acme
diff --git a/plugins/modules/acme_certificate.py b/plugins/modules/acme_certificate.py
index 537d9682..2e2e480a 100644
--- a/plugins/modules/acme_certificate.py
+++ b/plugins/modules/acme_certificate.py
@@ -38,9 +38,9 @@ description:
 notes:
    - "At least one of C(dest) and C(fullchain_dest) must be specified."
    - "This module includes basic account management functionality.
-      If you want to have more control over your ACME account, use the M(acme_account)
-      module and disable account management for this module using the C(modify_account)
-      option."
+      If you want to have more control over your ACME account, use the
+      M(community.crypto.acme_account) module and disable account management
+      for this module using the C(modify_account) option."
    - "This module was called C(letsencrypt) before Ansible 2.6. The usage
       did not change."
 seealso:
@@ -58,19 +58,19 @@ seealso:
   - name: ACME TLS ALPN Challenge Extension
     description: The specification of the C(tls-alpn-01) challenge (RFC 8737).
     link: https://www.rfc-editor.org/rfc/rfc8737.html-05
-  - module: acme_challenge_cert_helper
+  - module: community.crypto.acme_challenge_cert_helper
     description: Helps preparing C(tls-alpn-01) challenges.
-  - module: openssl_privatekey
+  - module: community.crypto.openssl_privatekey
     description: Can be used to create private keys (both for certificates and accounts).
-  - module: openssl_csr
+  - module: commuinty.crypto.openssl_csr
     description: Can be used to create a Certificate Signing Request (CSR).
-  - module: certificate_complete_chain
+  - module: comunity.crypto.certificate_complete_chain
     description: Allows to find the root certificate for the returned fullchain.
-  - module: acme_certificate_revoke
+  - module: community.crypto.acme_certificate_revoke
     description: Allows to revoke certificates.
-  - module: acme_account
+  - module: community.crypto.acme_account
     description: Allows to create, modify or delete an ACME account.
-  - module: acme_inspect
+  - module: community.crypto.acme_inspect
     description: Allows to debug problems.
 extends_documentation_fragment:
 - community.crypto.acme
@@ -81,7 +81,7 @@ options:
       - "The email address associated with this account."
       - "It will be used for certificate expiration warnings."
       - "Note that when C(modify_account) is not set to C(no) and you also
-         used the M(acme_account) module to specify more than one contact
+         used the M(community.crypto.acme_account) module to specify more than one contact
          for your account, this module will update your account and restrict
          it to the (at most one) contact email address specified here."
     type: str
@@ -103,9 +103,9 @@ options:
     description:
       - "Boolean indicating whether the module should create the account if
          necessary, and update its contact data."
-      - "Set to C(no) if you want to use the M(acme_account) module to manage
+      - "Set to C(no) if you want to use the M(community.crypto.acme_account) module to manage
          your account instead, and to avoid accidental creation of a new account
-         using an old key if you changed the account key with M(acme_account)."
+         using an old key if you changed the account key with M(community.crypto.acme_account)."
       - "If set to C(no), C(terms_agreed) and C(account_email) are ignored."
     type: bool
     default: yes
diff --git a/plugins/modules/acme_certificate_revoke.py b/plugins/modules/acme_certificate_revoke.py
index 22e16d78..c4b769ab 100644
--- a/plugins/modules/acme_certificate_revoke.py
+++ b/plugins/modules/acme_certificate_revoke.py
@@ -33,7 +33,7 @@ seealso:
   - name: Automatic Certificate Management Environment (ACME)
     description: The specification of the ACME protocol (RFC 8555).
     link: https://tools.ietf.org/html/rfc8555
-  - module: acme_inspect
+  - module: community.crypto.acme_inspect
     description: Allows to debug problems.
 extends_documentation_fragment:
 - community.crypto.acme
diff --git a/plugins/modules/acme_challenge_cert_helper.py b/plugins/modules/acme_challenge_cert_helper.py
index ec0e65ec..2e7e70ba 100644
--- a/plugins/modules/acme_challenge_cert_helper.py
+++ b/plugins/modules/acme_challenge_cert_helper.py
@@ -15,7 +15,7 @@ author: "Felix Fontein (@felixfontein)"
 short_description: Prepare certificates required for ACME challenges such as C(tls-alpn-01)
 description:
    - "Prepares certificates for ACME challenges such as C(tls-alpn-01)."
-   - "The raw data is provided by the M(acme_certificate) module, and needs to be
+   - "The raw data is provided by the M(community.crypto.acme_certificate) module, and needs to be
       converted to a certificate to be used for challenge validation. This module
       provides a simple way to generate the required certificates."
 seealso:
@@ -37,7 +37,8 @@ options:
     - tls-alpn-01
   challenge_data:
     description:
-      - "The C(challenge_data) entry provided by M(acme_certificate) for the challenge."
+      - "The C(challenge_data) entry provided by M(community.crypto.acme_certificate) for the
+         challenge."
     type: dict
     required: yes
   private_key_src:
diff --git a/plugins/modules/acme_inspect.py b/plugins/modules/acme_inspect.py
index 010c5a0b..eb7ca524 100644
--- a/plugins/modules/acme_inspect.py
+++ b/plugins/modules/acme_inspect.py
@@ -18,14 +18,14 @@ description:
       L(ACME protocol,https://tools.ietf.org/html/rfc8555),
       which is supported by CAs such as L(Let's Encrypt,https://letsencrypt.org/)."
    - "This module can be used to debug failed certificate request attempts,
-      for example when M(acme_certificate) fails or encounters a problem which
+      for example when M(community.crypto.acme_certificate) fails or encounters a problem which
       you wish to investigate."
    - "The module can also be used to directly access features of an ACME servers
       which are not yet supported by the Ansible ACME modules."
 notes:
    - "The I(account_uri) option must be specified for properly authenticated
       ACME v2 requests (except a C(new-account) request)."
-   - "Using the C(ansible) tool, M(acme_inspect) can be used to directly execute
+   - "Using the C(ansible) tool, M(community.crypto.acme_inspect) can be used to directly execute
       ACME requests without the need of writing a playbook. For example, the
       following command retrieves the ACME account with ID 1 from Let's Encrypt
       (assuming C(/path/to/key) is the correct private account key):
diff --git a/plugins/modules/certificate_complete_chain.py b/plugins/modules/certificate_complete_chain.py
index 8f7aa680..49ed0311 100644
--- a/plugins/modules/certificate_complete_chain.py
+++ b/plugins/modules/certificate_complete_chain.py
@@ -18,7 +18,7 @@ description:
        intermediate certificates from a given set of certificates, until it finds a root
        certificate in another given set of certificates."
     - "This can for example be used to find the root certificate for a certificate chain
-       returned by M(acme_certificate)."
+       returned by M(community.crypto.acme_certificate)."
     - "Note that this module does I(not) check for validity of the chains. It only
        checks that issuer and subject match, and that the signature is correct. It
        ignores validity dates and key usage completely. If you need to verify that a
diff --git a/plugins/modules/ecs_certificate.py b/plugins/modules/ecs_certificate.py
index 76ca875d..4507f400 100644
--- a/plugins/modules/ecs_certificate.py
+++ b/plugins/modules/ecs_certificate.py
@@ -332,9 +332,9 @@ options:
         type: str
         choices: [ P1Y, P2Y, P3Y ]
 seealso:
-    - module: openssl_privatekey
+    - module: community.crypto.openssl_privatekey
       description: Can be used to create private keys (both for certificates and accounts).
-    - module: openssl_csr
+    - module: community.crypto.openssl_csr
       description: Can be used to create a Certificate Signing Request (CSR).
 extends_documentation_fragment:
 - community.crypto.ecs_credential
diff --git a/plugins/modules/ecs_domain.py b/plugins/modules/ecs_domain.py
index 957a8739..566ec2df 100644
--- a/plugins/modules/ecs_domain.py
+++ b/plugins/modules/ecs_domain.py
@@ -73,9 +73,9 @@ options:
             - Only allowed if C(verification_method=email)
         type: str
 seealso:
-    - module: x509_certificate
+    - module: community.crypto.x509_certificate
       description: Can be used to request certificates from ECS, with C(provider=entrust).
-    - module: ecs_certificate
+    - module: community.crypto.ecs_certificate
       description: Can be used to request a Certificate from ECS using a verified domain.
 extends_documentation_fragment:
 - community.crypto.ecs_credential
diff --git a/plugins/modules/openssl_csr.py b/plugins/modules/openssl_csr.py
index f6633d0e..c6b56cd1 100644
--- a/plugins/modules/openssl_csr.py
+++ b/plugins/modules/openssl_csr.py
@@ -274,11 +274,11 @@ notes:
       keyUsage, extendedKeyUsage and basicConstraints only contain the requested values, whether
       OCSP Must Staple is as requested, and if the request was signed by the given private key.
 seealso:
-- module: x509_certificate
-- module: openssl_dhparam
-- module: openssl_pkcs12
-- module: openssl_privatekey
-- module: openssl_publickey
+- module: community.crypto.x509_certificate
+- module: community.crypto.openssl_dhparam
+- module: community.crypto.openssl_pkcs12
+- module: community.crypto.openssl_privatekey
+- module: community.crypto.openssl_publickey
 '''
 
 EXAMPLES = r'''
diff --git a/plugins/modules/openssl_csr_info.py b/plugins/modules/openssl_csr_info.py
index 72d0cfe4..c5fb9c9e 100644
--- a/plugins/modules/openssl_csr_info.py
+++ b/plugins/modules/openssl_csr_info.py
@@ -51,7 +51,7 @@ options:
         choices: [ auto, cryptography, pyopenssl ]
 
 seealso:
-- module: openssl_csr
+- module: community.crypto.openssl_csr
 '''
 
 EXAMPLES = r'''
diff --git a/plugins/modules/openssl_dhparam.py b/plugins/modules/openssl_dhparam.py
index 09b65020..6d683f2d 100644
--- a/plugins/modules/openssl_dhparam.py
+++ b/plugins/modules/openssl_dhparam.py
@@ -72,11 +72,11 @@ options:
 extends_documentation_fragment:
 - files
 seealso:
-- module: x509_certificate
-- module: openssl_csr
-- module: openssl_pkcs12
-- module: openssl_privatekey
-- module: 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'''
diff --git a/plugins/modules/openssl_pkcs12.py b/plugins/modules/openssl_pkcs12.py
index aaa1f793..2b7bb298 100644
--- a/plugins/modules/openssl_pkcs12.py
+++ b/plugins/modules/openssl_pkcs12.py
@@ -98,11 +98,11 @@ options:
 extends_documentation_fragment:
     - files
 seealso:
-- module: x509_certificate
-- module: openssl_csr
-- module: openssl_dhparam
-- module: openssl_privatekey
-- module: openssl_publickey
+- module: community.crypto.x509_certificate
+- module: community.crypto.openssl_csr
+- module: community.crypto.openssl_dhparam
+- module: community.crypto.openssl_privatekey
+- module: community.crypto.openssl_publickey
 '''
 
 EXAMPLES = r'''
diff --git a/plugins/modules/openssl_privatekey.py b/plugins/modules/openssl_privatekey.py
index d640a0d5..58391f93 100644
--- a/plugins/modules/openssl_privatekey.py
+++ b/plugins/modules/openssl_privatekey.py
@@ -187,11 +187,11 @@ options:
 extends_documentation_fragment:
 - files
 seealso:
-- module: x509_certificate
-- module: openssl_csr
-- module: openssl_dhparam
-- module: openssl_pkcs12
-- module: openssl_publickey
+- module: community.crypto.x509_certificate
+- module: community.crypto.openssl_csr
+- module: community.crypto.openssl_dhparam
+- module: community.crypto.openssl_pkcs12
+- module: community.crypto.openssl_publickey
 '''
 
 EXAMPLES = r'''
diff --git a/plugins/modules/openssl_privatekey_info.py b/plugins/modules/openssl_privatekey_info.py
index 16a8a92f..3190fa6d 100644
--- a/plugins/modules/openssl_privatekey_info.py
+++ b/plugins/modules/openssl_privatekey_info.py
@@ -65,7 +65,7 @@ options:
         choices: [ auto, cryptography, pyopenssl ]
 
 seealso:
-- module: openssl_privatekey
+- module: community.crypto.openssl_privatekey
 '''
 
 EXAMPLES = r'''
diff --git a/plugins/modules/openssl_publickey.py b/plugins/modules/openssl_publickey.py
index e5bcac03..1bcd48de 100644
--- a/plugins/modules/openssl_publickey.py
+++ b/plugins/modules/openssl_publickey.py
@@ -89,11 +89,11 @@ options:
 extends_documentation_fragment:
 - files
 seealso:
-- module: x509_certificate
-- module: openssl_csr
-- module: openssl_dhparam
-- module: openssl_pkcs12
-- module: openssl_privatekey
+- module: community.crypto.x509_certificate
+- module: community.crypto.openssl_csr
+- module: community.crypto.openssl_dhparam
+- module: community.crypto.openssl_pkcs12
+- module: community.crypto.openssl_privatekey
 '''
 
 EXAMPLES = r'''
diff --git a/plugins/modules/x509_certificate.py b/plugins/modules/x509_certificate.py
index 8df3adfd..5f5bc2a5 100644
--- a/plugins/modules/x509_certificate.py
+++ b/plugins/modules/x509_certificate.py
@@ -20,8 +20,9 @@ description:
     - The C(assertonly) provider is intended for use cases where one is only interested in
       checking properties of a supplied certificate. Please note that this provider has been
       deprecated in Ansible 2.9 and will be removed in Ansible 2.13. See the examples on how
-      to emulate C(assertonly) usage with M(x509_certificate_info), M(openssl_csr_info),
-      M(openssl_privatekey_info) and M(assert). This also allows more flexible checks than
+      to emulate C(assertonly) usage with M(community.crypto.x509_certificate_info),
+      M(community.crypto.openssl_csr_info), M(community.crypto.openssl_privatekey_info) and
+      M(ansible.builtin.assert). This also allows more flexible checks than
       the ones offered by the C(assertonly) provider.
     - The C(ownca) provider is intended for generating OpenSSL certificate signed with your own
       CA (Certificate Authority) certificate (self-signed certificate).
@@ -36,11 +37,13 @@ description:
       cryptography will be preferred as a backend over PyOpenSSL (unless the backend is forced with C(select_crypto_backend)).
       Please note that the PyOpenSSL backend was deprecated in Ansible 2.9 and will be removed in Ansible 2.13.
     - Note that this module was called C(openssl_certificate) when included directly in Ansible up to version 2.9.
-      When moved to the collection C(community.crypto), it was renamed to M(x509_certificate). From Ansible 2.10 on, it can
-      still be used by the old short name (or by C(ansible.builtin.openssl_certificate)), which redirects to
+      When moved to the collection C(community.crypto), it was renamed to
+      M(community.crypto.x509_certificate). From Ansible 2.10 on, it can still be used by the
+      old short name (or by C(ansible.builtin.openssl_certificate)), which redirects to
       C(community.crypto.x509_certificate). When using FQCNs or when using the
       L(collections,https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections-in-a-playbook)
-      keyword, the new name M(x509_certificate) should be used to avoid a deprecation warning.
+      keyword, the new name M(community.crypto.x509_certificate) should be used to avoid
+      a deprecation warning.
 requirements:
     - PyOpenSSL >= 0.15 or cryptography >= 1.6 (if using C(selfsigned) or C(assertonly) provider)
     - acme-tiny >= 4.0.0 (if using the C(acme) provider)
@@ -66,8 +69,9 @@ options:
             - Name of the provider to use to generate/retrieve the OpenSSL certificate.
             - The C(assertonly) provider will not generate files and fail if the certificate file is missing.
             - The C(assertonly) provider has been deprecated in Ansible 2.9 and will be removed in Ansible 2.13.
-              Please see the examples on how to emulate it with M(x509_certificate_info), M(openssl_csr_info),
-              M(openssl_privatekey_info) and M(assert).
+              Please see the examples on how to emulate it with
+              M(community.crypto.x509_certificate_info), M(community.crypto.openssl_csr_info),
+              M(community.crypto.openssl_privatekey_info) and M(ansible.builtin.assert).
             - "The C(entrust) provider was added for Ansible 2.9 and requires credentials for the
                L(Entrust Certificate Services,https://www.entrustdatacard.com/products/categories/ssl-certificates) (ECS) API."
             - Required if I(state) is C(present).
@@ -579,15 +583,16 @@ extends_documentation_fragment: files
 notes:
     - All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
     - Date specified should be UTC. Minutes and seconds are mandatory.
-    - For security reason, when you use C(ownca) provider, you should NOT run M(x509_certificate) on
-      a target machine, but on a dedicated CA machine. It is recommended not to store the CA private key
-      on the target machine. Once signed, the certificate can be moved to the target machine.
+    - For security reason, when you use C(ownca) provider, you should NOT run
+      M(community.general.x509_certificate) on a target machine, but on a dedicated CA machine. It
+      is recommended not to store the CA private key on the target machine. Once signed, the
+      certificate can be moved to the target machine.
 seealso:
-- module: openssl_csr
-- module: openssl_dhparam
-- module: openssl_pkcs12
-- module: openssl_privatekey
-- module: openssl_publickey
+- module: community.crypto.openssl_csr
+- module: community.crypto.openssl_dhparam
+- module: community.crypto.openssl_pkcs12
+- module: community.crypto.openssl_privatekey
+- module: community.crypto.openssl_publickey
 '''
 
 EXAMPLES = r'''
diff --git a/plugins/modules/x509_certificate_info.py b/plugins/modules/x509_certificate_info.py
index bd26ad8a..cf5e64ce 100644
--- a/plugins/modules/x509_certificate_info.py
+++ b/plugins/modules/x509_certificate_info.py
@@ -20,12 +20,14 @@ description:
       cryptography will be preferred as a backend over PyOpenSSL (unless the backend is forced with
       C(select_crypto_backend)). Please note that the PyOpenSSL backend was deprecated in Ansible 2.9
       and will be removed in Ansible 2.13.
-    - Note that this module was called C(openssl_certificate_info) when included directly in Ansible up to version 2.9.
-      When moved to the collection C(community.crypto), it was renamed to M(x509_certificate_info). From Ansible 2.10 on, it can
-      still be used by the old short name (or by C(ansible.builtin.openssl_certificate_info)), which redirects to
+    - Note that this module was called C(openssl_certificate_info) when included directly in Ansible
+      up to version 2.9.  When moved to the collection C(community.crypto), it was renamed to
+      M(community.crypto.x509_certificate_info). From Ansible 2.10 on, it can still be used by the
+      old short name (or by C(ansible.builtin.openssl_certificate_info)), which redirects to
       C(community.crypto.x509_certificate_info). When using FQCNs or when using the
       L(collections,https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections-in-a-playbook)
-      keyword, the new name M(x509_certificate_info) should be used to avoid a deprecation warning.
+      keyword, the new name M(community.crypto.x509_certificate_info) should be used to avoid
+      a deprecation warning.
 requirements:
     - PyOpenSSL >= 0.15 or cryptography >= 1.6
 author:
@@ -70,7 +72,7 @@ notes:
     - All timestamp values are provided in ASN.1 TIME format, i.e. following the C(YYYYMMDDHHMMSSZ) pattern.
       They are all in UTC.
 seealso:
-- module: x509_certificate
+- module: community.crypto.x509_certificate
 '''
 
 EXAMPLES = r'''
diff --git a/plugins/modules/x509_crl_info.py b/plugins/modules/x509_crl_info.py
index 2bd73adf..4b2b568f 100644
--- a/plugins/modules/x509_crl_info.py
+++ b/plugins/modules/x509_crl_info.py
@@ -34,7 +34,7 @@ notes:
     - All timestamp values are provided in ASN.1 TIME format, i.e. following the C(YYYYMMDDHHMMSSZ) pattern.
       They are all in UTC.
 seealso:
-    - module: x509_crl
+    - module: community.crypto.x509_crl
 '''
 
 EXAMPLES = r'''