From 989b8f059b4e6f6ad4267e1435043bae935750db Mon Sep 17 00:00:00 2001 From: James Kasten Date: Fri, 27 Mar 2015 15:20:43 -0700 Subject: [PATCH] Update documentation --- docs/api/client/apache.rst | 29 ------------ docs/api/client/plugins/apache.rst | 29 ++++++++++++ docs/api/client/plugins/standalone.rst | 11 +++++ docs/api/client/standalone_authenticator.rst | 5 -- .../plugins/letsencrypt_example_plugins.py | 2 + .../client/plugins/apache/configurator.py | 47 +++++++++++-------- 6 files changed, 69 insertions(+), 54 deletions(-) delete mode 100644 docs/api/client/apache.rst create mode 100644 docs/api/client/plugins/apache.rst create mode 100644 docs/api/client/plugins/standalone.rst delete mode 100644 docs/api/client/standalone_authenticator.rst diff --git a/docs/api/client/apache.rst b/docs/api/client/apache.rst deleted file mode 100644 index e69826cf9..000000000 --- a/docs/api/client/apache.rst +++ /dev/null @@ -1,29 +0,0 @@ -:mod:`letsencrypt.client.apache` --------------------------------- - -.. automodule:: letsencrypt.client.apache - :members: - -:mod:`letsencrypt.client.apache.configurator` -============================================= - -.. automodule:: letsencrypt.client.apache.configurator - :members: - -:mod:`letsencrypt.client.apache.dvsni` -============================================= - -.. automodule:: letsencrypt.client.apache.dvsni - :members: - -:mod:`letsencrypt.client.apache.obj` -==================================== - -.. automodule:: letsencrypt.client.apache.obj - :members: - -:mod:`letsencrypt.client.apache.parser` -======================================= - -.. automodule:: letsencrypt.client.apache.parser - :members: diff --git a/docs/api/client/plugins/apache.rst b/docs/api/client/plugins/apache.rst new file mode 100644 index 000000000..6e6e6c462 --- /dev/null +++ b/docs/api/client/plugins/apache.rst @@ -0,0 +1,29 @@ +:mod:`letsencrypt.client.plugins.apache` +---------------------------------------- + +.. automodule:: letsencrypt.client.plugins.apache + :members: + +:mod:`letsencrypt.client.plugins.apache.configurator` +===================================================== + +.. automodule:: letsencrypt.client.plugins.apache.configurator + :members: + +:mod:`letsencrypt.client.plugins.apache.dvsni` +============================================== + +.. automodule:: letsencrypt.client.plugins.apache.dvsni + :members: + +:mod:`letsencrypt.client.plugins.apache.obj` +============================================ + +.. automodule:: letsencrypt.client.plugins.apache.obj + :members: + +:mod:`letsencrypt.client.plugins.apache.parser` +=============================================== + +.. automodule:: letsencrypt.client.plugins.apache.parser + :members: diff --git a/docs/api/client/plugins/standalone.rst b/docs/api/client/plugins/standalone.rst new file mode 100644 index 000000000..44cf4b8ca --- /dev/null +++ b/docs/api/client/plugins/standalone.rst @@ -0,0 +1,11 @@ +:mod:`letsencrypt.client.plugins.standalone` +-------------------------------------------- + +.. automodule:: letsencrypt.client.plugins.standalone + :members: + +:mod:`letsencrypt.client.plugins.standalone.authenticator` +========================================================== + +.. automodule:: letsencrypt.client.plugins.standalone.authenticator + :members: diff --git a/docs/api/client/standalone_authenticator.rst b/docs/api/client/standalone_authenticator.rst deleted file mode 100644 index d05f4f057..000000000 --- a/docs/api/client/standalone_authenticator.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.client.standalone_authenticator` --------------------------------------------------- - -.. automodule:: letsencrypt.client.standalone_authenticator - :members: diff --git a/examples/plugins/letsencrypt_example_plugins.py b/examples/plugins/letsencrypt_example_plugins.py index 6817c7f1d..987a2b33b 100644 --- a/examples/plugins/letsencrypt_example_plugins.py +++ b/examples/plugins/letsencrypt_example_plugins.py @@ -14,3 +14,5 @@ class Authenticator(object): # Implement all methods from IAuthenticator, remembering to add # "self" as first argument, e.g. def prepare(self)... + + # For full examples, see letsencrypt.client.plugins diff --git a/letsencrypt/client/plugins/apache/configurator.py b/letsencrypt/client/plugins/apache/configurator.py index fb5ba7bd1..028c32bbb 100644 --- a/letsencrypt/client/plugins/apache/configurator.py +++ b/letsencrypt/client/plugins/apache/configurator.py @@ -68,12 +68,12 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): :type config: :class:`~letsencrypt.client.interfaces.IConfig` :ivar parser: Handles low level parsing - :type parser: :class:`letsencrypt.client.plugins.apache.parser` + :type parser: :class:`~letsencrypt.client.plugins.apache.parser` :ivar tup version: version of Apache :ivar list vhosts: All vhosts found in the configuration (:class:`list` of - :class:`letsencrypt.client.plugins.apache.obj.VirtualHost`) + :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost`) :ivar dict assoc: Mapping between domains and vhosts @@ -204,7 +204,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): :param str target_name: domain name :returns: ssl vhost associated with name - :rtype: :class:`letsencrypt.client.plugins.apache.obj.VirtualHost` + :rtype: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` """ # Allows for domain names to be associated with a virtual host @@ -245,7 +245,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): :param str domain: domain name to associate :param vhost: virtual host to associate with domain - :type vhost: :class:`letsencrypt.client.plugins.apache.obj.VirtualHost` + :type vhost: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` """ self.assoc[domain] = vhost @@ -282,7 +282,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): """Helper function for get_virtual_hosts(). :param host: In progress vhost whose names will be added - :type host: :class:`letsencrypt.client.plugins.apache.obj.VirtualHost` + :type host: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` """ name_match = self.aug.match(("%s//*[self::directive=~regexp('%s')] | " @@ -303,7 +303,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): :param str path: Augeas path to virtual host :returns: newly created vhost - :rtype: :class:`letsencrypt.client.plugins.apache.obj.VirtualHost` + :rtype: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` """ addrs = set() @@ -327,7 +327,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): """Returns list of virtual hosts found in the Apache configuration. :returns: List of - :class:`letsencrypt.client.plugins.apache.obj.VirtualHost` objects + :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` objects found in configuration :rtype: list @@ -405,7 +405,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): """Checks to see if the server is ready for SNI challenges. :param vhost: VirtualHost to check SNI compatibility - :type vhost: :class:`letsencrypt.client.plugins.apache.obj.VirtualHost` + :type vhost: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` :param str default_addr: TODO - investigate function further @@ -437,10 +437,11 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): .. note:: This function saves the configuration :param nonssl_vhost: Valid VH that doesn't have SSLEngine on - :type nonssl_vhost: :class:`~apache.obj.VirtualHost` + :type nonssl_vhost: + :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` :returns: SSL vhost - :rtype: :class:`letsencrypt.client.plugins.apache.obj.VirtualHost` + :rtype: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` """ avail_fp = nonssl_vhost.filep @@ -560,13 +561,13 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): .. note:: This function saves the configuration :param ssl_vhost: Destination of traffic, an ssl enabled vhost - :type ssl_vhost: :class:`~apache.obj.VirtualHost` + :type ssl_vhost: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` :param unused_options: Not currently used :type unused_options: Not Available :returns: Success, general_vhost (HTTP vhost) - :rtype: (bool, :class:`~apache.obj.VirtualHost`) + :rtype: (bool, :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost`) """ if not mod_loaded("rewrite_module", self.config.apache_ctl): @@ -618,7 +619,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): -1 is also returned in case of no redirection/rewrite directives :param vhost: vhost to check - :type vhost: :class:`letsencrypt.client.plugins.apache.obj.VirtualHost` + :type vhost: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` :returns: Success, code value... see documentation :rtype: bool, int @@ -650,10 +651,13 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): """Creates an http_vhost specifically to redirect for the ssl_vhost. :param ssl_vhost: ssl vhost - :type ssl_vhost: :class:`~apache.obj.VirtualHost` + :type ssl_vhost: + :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` - :returns: Success, vhost - :rtype: (bool, :class:`~apache.obj.VirtualHost`) + :returns: tuple of the form + (`success`, + :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost`) + :rtype: tuple """ # Consider changing this to a dictionary check @@ -735,7 +739,8 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): if not conflict: returns space separated list of new host addrs :param ssl_vhost: SSL Vhost to check for possible port 80 redirection - :type ssl_vhost: :class:`~apache.obj.VirtualHost` + :type ssl_vhost: + :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` :returns: TODO :rtype: TODO @@ -768,10 +773,12 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): Consider changing this into a dict check :param ssl_vhost: ssl vhost to check - :type ssl_vhost: :class:`~apache.obj.VirtualHost` + :type ssl_vhost: + :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` :returns: HTTP vhost or None if unsuccessful - :rtype: :class:`~apache.obj.VirtualHost` or None + :rtype: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` + or None """ # _default_:443 check @@ -861,7 +868,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator): .. todo:: Make sure link is not broken... :param vhost: vhost to enable - :type vhost: :class:`~apache.obj.VirtualHost` + :type vhost: :class:`~letsencrypt.client.plugins.apache.obj.VirtualHost` :returns: Success :rtype: bool