Improve letsencrypt.acme docs.

docs/api/acme.rst

@@ -0,0 +1,51 @@
+:mod:`letsencrypt.acme`
+=======================
+
+.. automodule:: letsencrypt.acme
+   :members:
+
+
+Interfaces
+----------
+
+.. automodule:: letsencrypt.acme.interfaces
+   :members:
+
+Messages
+--------
+
+.. automodule:: letsencrypt.acme.messages
+   :members:
+
+
+Challenges
+----------
+
+.. automodule:: letsencrypt.acme.challenges
+   :members:
+
+
+Other ACME objects
+------------------
+.. automodule:: letsencrypt.acme.other
+   :members:
+
+
+Errors
+------
+
+.. automodule:: letsencrypt.acme.errors
+   :members:
+
+
+   :members:
+
+
+Utilities
+---------
+
+.. automodule:: letsencrypt.acme.util
+   :members:
+
+.. automodule:: letsencrypt.acme.jose
+   :members:

docs/api/acme/challenges.rst

@@ -1,5 +0,0 @@
-:mod:`letsencrypt.acme.challenges`
-----------------------------------
-
-.. automodule:: letsencrypt.acme.challenges
-   :members:

docs/api/acme/errors.rst

@@ -1,5 +0,0 @@
-:mod:`letsencrypt.acme.errors`
-------------------------------
-
-.. automodule:: letsencrypt.acme.errors
-   :members:

docs/api/acme/interfaces.rst

@@ -1,5 +0,0 @@
-:mod:`letsencrypt.acme.interfaces`
-----------------------------------
-
-.. automodule:: letsencrypt.acme.interfaces
-   :members:

docs/api/acme/jose.rst

@@ -1,5 +0,0 @@
-:mod:`letsencrypt.acme.jose`
-----------------------------
-
-.. automodule:: letsencrypt.acme.jose
-   :members:

docs/api/acme/messages.rst

@@ -1,5 +0,0 @@
-:mod:`letsencrypt.acme.messages`
---------------------------------
-
-.. automodule:: letsencrypt.acme.messages
-   :members:

docs/api/acme/other.rst

@@ -1,5 +0,0 @@
-:mod:`letsencrypt.acme.other`
------------------------------
-
-.. automodule:: letsencrypt.acme.other
-   :members:

docs/api/acme/util.rst

@@ -1,5 +0,0 @@
-:mod:`letsencrypt.acme.util`
-----------------------------
-
-.. automodule:: letsencrypt.acme.util
-   :members:

docs/conf.py

@@ -54,6 +54,9 @@ extensions = [
     'repoze.sphinx.autointerface',
 ]
 
+autodoc_member_order = 'bysource'
+autodoc_default_flags = ['show-inheritance']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

letsencrypt/acme/__init__.py

@@ -1 +1,22 @@
-"""ACME protocol implementation."""
+"""ACME protocol implementation.
+
+.. warning:: This module is an implementation of the draft `ACME
+  protocol version 00`_, and not the latest (as of time of writing),
+  "RESTified" `ACME protocol version 01`_. It should work with the
+  server from the `Node.js implementation`_,  but will not work with
+  Boulder_.
+
+
+.. _`ACME protocol`: https://github.com/letsencrypt/acme-spec
+
+.. _`ACME protocol version 00`:
+  https://github.com/letsencrypt/acme-spec/blob/v00/draft-barnes-acme.md
+
+.. _`ACME protocol version 01`:
+  https://github.com/letsencrypt/acme-spec/blob/v01/draft-barnes-acme.md
+
+.. _Boulder: https://github.com/letsencrypt/boulder
+
+.. _`Node.js implementation`: https://github.com/letsencrypt/node-acme
+
+"""

letsencrypt/acme/interfaces.py

@@ -18,7 +18,6 @@ class IJSONSerializable(zope.interface.Interface):
             objects, that haven't been serialized yet, which is fine as
             long as :func:`letsencrypt.acme.util.dump_ijsonserializable`
             is used.
-        :rtype: dict
 
         """
 

letsencrypt/acme/messages.py

@@ -82,7 +82,13 @@ class Message(util.TypedACMEObject):
 
 @Message.register  # pylint: disable=too-few-public-methods
 class Challenge(Message):
-    """ACME "challenge" message."""
+    """ACME "challenge" message.
+
+    :ivar str nonce: Random data, **not** base64-encoded.
+    :ivar list challenges: List of
+        :class:`~letsencrypt.acme.challenges.Challenge` objects.
+
+    """
     acme_type = "challenge"
     schema = util.load_schema(acme_type)
     __slots__ = ("session_id", "nonce", "challenges", "combinations")
@@ -119,11 +125,7 @@ class Challenge(Message):
 
 @Message.register  # pylint: disable=too-few-public-methods
 class ChallengeRequest(Message):
-    """ACME "challengeRequest" message.
-
-    :ivar str identifier: Domain name.
-
-    """
+    """ACME "challengeRequest" message."""
     acme_type = "challengeRequest"
     schema = util.load_schema(acme_type)
     __slots__ = ("identifier",)
@@ -140,7 +142,11 @@ class ChallengeRequest(Message):
 
 @Message.register  # pylint: disable=too-few-public-methods
 class Authorization(Message):
-    """ACME "authorization" message."""
+    """ACME "authorization" message.
+
+    :ivar jwk: :class:`letsencrypt.acme.other.JWK`
+
+    """
     acme_type = "authorization"
     schema = util.load_schema(acme_type)
     __slots__ = ("recovery_token", "identifier", "jwk")
@@ -168,11 +174,11 @@ class Authorization(Message):
 class AuthorizationRequest(Message):
     """ACME "authorizationRequest" message.
 
-    :ivar str session_id: "sessionID" from the server challenge
-    :ivar str nonce: Nonce from the server challenge
-    :ivar list responses: List of completed challenges
+    :ivar str nonce: Random data from the corresponding
+        :attr:`Challenge.nonce`, **not** base64-encoded.
+    :ivar list responses: List of completed challenges (
+        :class:`letsencrypt.acme.challenges.ChallengeResponse`).
     :ivar signature: Signature (:class:`letsencrypt.acme.other.Signature`).
-    :ivar contact: TODO
 
     """
     acme_type = "authorizationRequest"

setup.py

@@ -44,7 +44,7 @@ dev_extras = [
 
 docs_extras = [
     'repoze.sphinx.autointerface',
-    'Sphinx',
+    'Sphinx>=1.0',  # autodoc_member_order = 'bysource', autodoc_default_flags
     'sphinx_rtd_theme',
 ]