ACME: improve documentation (#44691)

* Override description for account_key_src and account_key_content to also mention private_key_*.

* Convert generic OpenSSL/cryptography remark from description to note.

This avoids the whole description list to be sorted alphabetically, which will be done by plugin_docs.py in case description is mentioned in both module fragment and module itself.

* Moving more notes to the notes: section.

* Uniformization of first paragraph. Mainly mention ACME supporting CAs, and only then mention Let's Encrypt as one of them.

* Adjusting to current drafts.

* Adjusting to updated drafts.

* Harmonizing short module descriptions.

* Referencing helper modules.

* Move general Let's Encrypt remark to doc fragment.

* Changing some Let's Encrypt references to more generic statements.

lib/ansible/modules/crypto/acme/acme_certificate_revoke.py

@@ -18,15 +18,15 @@ DOCUMENTATION = '''
 module: acme_certificate_revoke
 author: "Felix Fontein (@felixfontein)"
 version_added: "2.7"
-short_description: Revoke certificates with the ACME protocol.
+short_description: Revoke certificates with the ACME protocol
 description:
-   - "Allows to revoke certificates with the ACME protocol, for example
-      for certificates obtained by the M(acme_certificate) module. The
-      ACME protocol is used by some Certificate Authorities such as
-      L(Let's Encrypt,https://letsencrypt.org/)."
-   - "Note that exactly one of C(account_key_src), C(account_key_content),
+   - "Allows to revoke certificates issued by a CA supporting the
+      L(ACME protocol,https://tools.ietf.org/html/draft-ietf-acme-acme-14),
+      such as L(Let's Encrypt,https://letsencrypt.org/)."
+notes:
+   - "Exactly one of C(account_key_src), C(account_key_content),
       C(private_key_src) or C(private_key_content) must be specified."
-   - "Also note that trying to revoke an already revoked certificate
+   - "Trying to revoke an already revoked certificate
       should result in an unchanged status, even if the revocation reason
       was different than the one specified here. Also, depending on the
       server, it can happen that some other error is returned if the
@@ -38,6 +38,29 @@ options:
     description:
       - "Path to the certificate to revoke."
     required: yes
+  account_key_src:
+    description:
+      - "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 ...). Any other tool creating
+         private keys in PEM format can be used as well."
+      - "Mutually exclusive with C(account_key_content)."
+      - "Required if C(account_key_content) is not used."
+  account_key_content:
+    description:
+      - "Content of the ACME account RSA or Elliptic Curve key."
+      - "Note that exactly one of C(account_key_src), C(account_key_content),
+         C(private_key_src) or C(private_key_content) must be specified."
+      - "I(Warning): the content will be written into a temporary file, which will
+         be deleted by Ansible when the module completes. Since this is an
+         important private key — it can be used to change the account key,
+         or to revoke your certificates without knowing their private keys
+         —, this might not be acceptable."
+      - "In case C(cryptography) is used, the content is not written into a
+         temporary file. It can still happen that it is written to disk by
+         Ansible in the process of moving the module with its argument to
+         the node where it is executed."
   private_key_src:
     description:
       - "Path to the certificate's private key."