Add notes and todos, rephrase and tidy up

docs/conf.py

@@ -38,6 +38,7 @@ release = u''
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.todo',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -67,6 +68,8 @@ exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
 
 # -- Options for HTML output -------------------------------------------------
 

docs/getting-started/2-installing.rst

@@ -17,13 +17,14 @@ You can install the chart with the following command:
         --namespace kube-system \
         stable/cert-manager
 
-**NOTE**: if your cluster does not use RBAC (Role Based Access Control), you
-will need to disable creation of RBAC resources by adding
-``--set rbac.create=false`` to your ``helm install`` command above.
-
 The default cert-manager configuration is good for the majority of users, but a
 full list of the available options can be found in the `Helm chart README`_.
 
+.. note::
+   If your cluster does not use RBAC (Role Based Access Control), you
+   will need to disable creation of RBAC resources by adding
+   ``--set rbac.create=false`` to your ``helm install`` command above.
+
 With static manifests
 =====================
 

docs/reference/certificates.rst

@@ -33,7 +33,6 @@ A simple Certificate could be defined as:
        # The default value is Issuer (i.e. a locally namespaced Issuer)
        kind: Issuer
 
-
 This Certificate will tell cert-manager to attempt to use the Issuer
 named ``letsencrypt-prod`` to obtain a certificate key pair for the
 ``foo.example.com`` and ``bar.example.com`` domains. If successful, the resulting

docs/reference/issuers/acme/http01.rst

@@ -3,10 +3,11 @@ HTTP01 Challenge Provider
 =========================
 
 In order to allow HTTP01 challenges to be solved, we must enable the HTTP01
-challenge provider on our Issuer resource. This can be done through setting the
-``http01`` field on the ``issuer.spec.acme`` stanza. Cert-manager will then
-create and manage Ingress rules in the Kubernetes API server in order to solve
-HTTP-01 based challenges.
+challenge provider on our Issuer resource.
+
+This is done through setting the ``http01`` field on the ``issuer.spec.acme``
+stanza. Cert-manager will then attempt to solve ACME HTTP-01 challenges by
+using Ingress resources
 
 .. code-block:: yaml
    :linenos:
@@ -23,3 +24,6 @@ HTTP-01 based challenges.
        privateKeySecretRef:
          name: example-issuer-account-key
        http01: {}
+
+.. todo::
+   Write a full description of how HTTP01 challenge validation works

docs/tutorials/acme/migrating-from-kube-lego.rst

@@ -20,7 +20,8 @@ Distinct issuance sources per Certificate   Not supported
 Ingress controller support (ACME)           GCE, nginx                          All
 =========================================   ================================    =====================
 
-This guide will walk through how you can safely migrate your kube-lego installation to cert-manager, without service interruption.
+This guide will walk through how you can safely migrate your kube-lego
+installation to cert-manager, without service interruption.
 
 By the end of the guide, we should have:
 
@@ -44,7 +45,10 @@ By the end of the guide, we should have:
 1. Scale down kube-lego
 =======================
 
-Before we begin deploying cert-manager, it is best we scale our kube-lego deployment down to 0 replicas. This will prevent the two controllers potentially 'fighting' each other. If you deployed kube-lego using the official deployment YAMLs, a command like so should do:
+Before we begin deploying cert-manager, it is best we scale our kube-lego
+deployment down to 0 replicas. This will prevent the two controllers
+potentially 'fighting' each other. If you deployed kube-lego using the official
+deployment YAMLs, a command like so should do:
 
 .. code-block:: shell