Improving documentation: make more general (less Let's Encrypt specific), and improve formatting. (#39979)

lib/ansible/modules/web_infrastructure/acme_certificate.py

@@ -18,23 +18,23 @@ DOCUMENTATION = '''
 module: acme_certificate
 author: "Michael Gruener (@mgruener)"
 version_added: "2.2"
-short_description: Create SSL certificates with Let's Encrypt
+short_description: Create SSL certificates with an ACME protocol endpoint
 description:
-   - "Create and renew SSL certificates with Let's Encrypt. Let's Encrypt is a
+   - "Create and renew SSL certificates with a CA supporting the ACME protocol,
-      free, automated, and open certificate authority (CA), run for the
+      such as Let's Encrypt (U(https://letsencrypt.org)). For details see
-      public's benefit. For details see U(https://letsencrypt.org). The current
+      U(https://letsencrypt.org). The current implementation supports the
-      implementation supports the http-01 and dns-01 challenges."
+      C(http-01) and C(dns-01) challenges."
    - "To use this module, it has to be executed twice. Either as two
       different tasks in the same run or during two runs. Note that the output
       of the first run needs to be recorded and passed to the second run as the
       module argument C(data)."
    - "Between these two tasks you have to fulfill the required steps for the
-      chosen challenge by whatever means necessary. For http-01 that means
+      chosen challenge by whatever means necessary. For C(http-01) that means
       creating the necessary challenge file on the destination webserver. For
-      dns-01 the necessary dns record has to be created.
+      C(dns-01) the necessary dns record has to be created.
       It is I(not) the responsibility of this module to perform these steps."
    - "For details on how to fulfill these challenges, you might have to read through
-      U(https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-8).
+      U(https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-8).
       Also, consider the examples provided for this module."
    - "Although the defaults are chosen so that the module can be used with
       the Let's Encrypt CA, the module can be used with any service using the ACME
@@ -48,7 +48,7 @@ requirements:
 options:
   account_key_src:
     description:
-      - "Path to a file containing the Let's Encrypt account RSA or Elliptic Curve
+      - "Path to a file containing the ACME account RSA or Elliptic Curve
          key."
       - "RSA keys can be created with C(openssl rsa ...). Elliptic curve keys can
          be created with C(openssl ecparam -genkey ...)."
@@ -57,7 +57,7 @@ options:
     aliases: [ account_key ]
   account_key_content:
     description:
-      - "Content of the Let's Encrypt account RSA or Elliptic Curve key."
+      - "Content of the ACME account RSA or Elliptic Curve key."
       - "Mutually exclusive with C(account_key_src)."
       - "Required if C(account_key_src) is not used."
       - "Warning: the content will be written into a temporary file, which will
@@ -74,26 +74,23 @@ options:
     description:
       - "The ACME directory to use. This is the entry point URL to access
          CA server API."
-      - "For safety reasons the default is set to the Let's Encrypt staging server.
+      - "For safety reasons the default is set to the Let's Encrypt staging
-         This will create technically correct, but untrusted certificates."
+         server (for the ACME v1 protocol). This will create technically correct,
-      - "You can find URLs of staging endpoints here:
+         but untrusted certificates."
+      - "For Let's Encrypt, all staging endpoints can be found here:
          U(https://letsencrypt.org/docs/staging-environment/)"
-      - "The production Let's Encrypt ACME v1 directory URL, which produces properly
+      - "For Let's Encrypt, the production directory URL for ACME v1 is
-         trusted certificates, is U(https://acme-v01.api.letsencrypt.org/directory)."
+         U(https://acme-v01.api.letsencrypt.org/directory), and the production
-      - "The production Let's Encrypt ACME v2 directory URL, which produces properly
+         directory URL for ACME v2 is U(https://acme-v02.api.letsencrypt.org/directory)."
-         trusted certificates, including wildcard certificates, is
+      - "I(Warning): So far, the module has only been tested against Let's Encrypt
-         U(https://acme-v02.api.letsencrypt.org/directory)."
+         (staging and production) and against the Pebble testing server
+         (U(https://github.com/letsencrypt/Pebble))."
     default: https://acme-staging.api.letsencrypt.org/directory
   acme_version:
     description:
       - "The ACME version of the endpoint."
       - "Must be 1 for the classic Let's Encrypt ACME endpoint, or 2 for the
-         new ACME v2 endpoint."
+         new standardized ACME v2 endpoint."
-      - "I(Warning): ACME v2 support is currently experimental, as the Let's Encrypt
-         production ACME v2 endpoint is still under development. The code is tested
-         against the latest staging endpoint as well as the Pebble testing server,
-         but there could be bugs which will only appear with a newer version of these
-         or with the production ACME v2 endpoint."
     default: 1
     choices: [1, 2]
     version_added: "2.5"
@@ -122,9 +119,10 @@ options:
       - "The CSR may contain multiple Subject Alternate Names, but each one
          will lead to an individual challenge that must be fulfilled for the
          CSR to be signed."
-      - "Note: the private key used to create the CSR I(must not) be the the
+      - "I(Note): the private key used to create the CSR I(must not) be the the
          account key. This is a bad idea from a security point of view, and
-         Let's Encrypt will not accept the CSR."
+         the CA should not accept the CSR. Let's Encrypt will return an error
+         in this case."
     required: true
     aliases: ['src']
   data:
@@ -165,7 +163,7 @@ options:
   validate_certs:
     description:
       - Whether calls to the ACME directory will validate TLS certificates.
-      - I(Warning:) Should I(only ever) be set to C(false) for testing purposes,
+      - I(Warning:) Should I(only ever) be set to C(no) for testing purposes,
         for example when testing against a local Pebble server.
     type: bool
     default: 'yes'
@@ -311,12 +309,12 @@ challenge_data:
       sample: IlirfxKKXA...17Dt3juxGJ-PCt92wr-oA
     record:
       description: the full DNS record's name for the challenge
-      returned: changed and challenge is dns-01
+      returned: changed and challenge is C(dns-01)
       type: string
       sample: _acme-challenge.example.com
       version_added: "2.5"
 challenge_data_dns:
-  description: list of TXT values per DNS record, in case challenge is dns-01
+  description: list of TXT values per DNS record, in case challenge is C(dns-01)
   returned: changed
   type: dict
   version_added: "2.5"
@@ -326,7 +324,7 @@ authorizations:
   type: complex
   contains:
       authorization:
-        description: ACME authorization object. See https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-7.1.4
+        description: ACME authorization object. See U(https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.1.4)
         returned: success
         type: dict
 order_uri: