From ca2bbc13a328ae193cf36c23ab9a4d2aacefbc17 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Tue, 24 Feb 2015 14:39:26 +0000 Subject: [PATCH] Improve letsencrypt.acme docs. --- docs/api/acme.rst | 51 ++++++++++++++++++++++++++++++++++ docs/api/acme/challenges.rst | 5 ---- docs/api/acme/errors.rst | 5 ---- docs/api/acme/interfaces.rst | 5 ---- docs/api/acme/jose.rst | 5 ---- docs/api/acme/messages.rst | 5 ---- docs/api/acme/other.rst | 5 ---- docs/api/acme/util.rst | 5 ---- docs/conf.py | 3 ++ letsencrypt/acme/__init__.py | 23 ++++++++++++++- letsencrypt/acme/interfaces.py | 1 - letsencrypt/acme/messages.py | 28 +++++++++++-------- setup.py | 2 +- 13 files changed, 94 insertions(+), 49 deletions(-) create mode 100644 docs/api/acme.rst delete mode 100644 docs/api/acme/challenges.rst delete mode 100644 docs/api/acme/errors.rst delete mode 100644 docs/api/acme/interfaces.rst delete mode 100644 docs/api/acme/jose.rst delete mode 100644 docs/api/acme/messages.rst delete mode 100644 docs/api/acme/other.rst delete mode 100644 docs/api/acme/util.rst diff --git a/docs/api/acme.rst b/docs/api/acme.rst new file mode 100644 index 000000000..04c33917a --- /dev/null +++ b/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: diff --git a/docs/api/acme/challenges.rst b/docs/api/acme/challenges.rst deleted file mode 100644 index 373748d61..000000000 --- a/docs/api/acme/challenges.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.acme.challenges` ----------------------------------- - -.. automodule:: letsencrypt.acme.challenges - :members: diff --git a/docs/api/acme/errors.rst b/docs/api/acme/errors.rst deleted file mode 100644 index 53132bd15..000000000 --- a/docs/api/acme/errors.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.acme.errors` ------------------------------- - -.. automodule:: letsencrypt.acme.errors - :members: diff --git a/docs/api/acme/interfaces.rst b/docs/api/acme/interfaces.rst deleted file mode 100644 index 5ed652834..000000000 --- a/docs/api/acme/interfaces.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.acme.interfaces` ----------------------------------- - -.. automodule:: letsencrypt.acme.interfaces - :members: diff --git a/docs/api/acme/jose.rst b/docs/api/acme/jose.rst deleted file mode 100644 index d82dc1f15..000000000 --- a/docs/api/acme/jose.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.acme.jose` ----------------------------- - -.. automodule:: letsencrypt.acme.jose - :members: diff --git a/docs/api/acme/messages.rst b/docs/api/acme/messages.rst deleted file mode 100644 index d231f9c52..000000000 --- a/docs/api/acme/messages.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.acme.messages` --------------------------------- - -.. automodule:: letsencrypt.acme.messages - :members: diff --git a/docs/api/acme/other.rst b/docs/api/acme/other.rst deleted file mode 100644 index 8372e3028..000000000 --- a/docs/api/acme/other.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.acme.other` ------------------------------ - -.. automodule:: letsencrypt.acme.other - :members: diff --git a/docs/api/acme/util.rst b/docs/api/acme/util.rst deleted file mode 100644 index 960cf8882..000000000 --- a/docs/api/acme/util.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.acme.util` ----------------------------- - -.. automodule:: letsencrypt.acme.util - :members: diff --git a/docs/conf.py b/docs/conf.py index 2f25c9a7b..2a29b9dd3 100644 --- a/docs/conf.py +++ b/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'] diff --git a/letsencrypt/acme/__init__.py b/letsencrypt/acme/__init__.py index 69418608b..95744bbd5 100644 --- a/letsencrypt/acme/__init__.py +++ b/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 + +""" diff --git a/letsencrypt/acme/interfaces.py b/letsencrypt/acme/interfaces.py index a106f2aca..b6e40a436 100644 --- a/letsencrypt/acme/interfaces.py +++ b/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 """ diff --git a/letsencrypt/acme/messages.py b/letsencrypt/acme/messages.py index a673631fa..4f0b43759 100644 --- a/letsencrypt/acme/messages.py +++ b/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" diff --git a/setup.py b/setup.py index 5a5361a1c..179fda443 100755 --- a/setup.py +++ b/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', ]