Merge pull request #109 from kuba/docs

Docs

letsencrypt/client/apache_configurator.py

@@ -64,10 +64,10 @@ class VH(object):
 
 
 class ApacheConfigurator(augeas_configurator.AugeasConfigurator):
-    """
-    State of Configurator:
-    This code has been tested under Ubuntu 12.04 Apache 2.2
-    and this code works for Ubuntu 14.04 Apache 2.4. Further
+    """Apache configurator.
+
+    State of Configurator: This code has been tested under Ubuntu 12.04
+    Apache 2.2 and this code works for Ubuntu 14.04 Apache 2.4. Further
     notes below.
 
     This class was originally developed for Apache 2.2 and has not seen a
@@ -87,6 +87,7 @@ class ApacheConfigurator(augeas_configurator.AugeasConfigurator):
     This class will eventually derive from a generic Configurator class
     so that other Configurators (like Nginx) can be developed and interoperate
     with the client.
+
     """
     def __init__(self, server_root=CONFIG.SERVER_ROOT):
         super(ApacheConfigurator, self).__init__()
@@ -1238,14 +1239,14 @@ LogLevel warn \n\
     def dvsni_perform(self, chall_dict):
         """Peform a DVSNI challenge.
 
-        chall_dict composed of:
+        `chall_dict` composed of:
 
         list_sni_tuple:
-            List of tuples with form `(addr, r, nonce)`
-            `addr` (`string`), `r` (base64 `str`), `nonce` (hex `str`)
+            List of tuples with form `(addr, r, nonce)`, where
+            `addr` (`str`), `r` (base64 `str`), `nonce` (hex `str`)
 
         dvsni_key:
-            :class:`client.Client.Key`
+            DVSNI key (:class:`letsencrypt.client.client.Client.Key`)
 
         :param dict chall_dict: dvsni challenge - see documentation
 
@@ -1315,11 +1316,11 @@ LogLevel warn \n\
         Result: Apache config includes virtual servers for issued challs
 
         :param list list_sni_tuple: list of tuples with the form
-            `(addr, y, nonce)`, where `addr` is `str`, y is `byte array`,
-            `nonce` is `str`
+            `(addr, y, nonce)`, where `addr` is `str`, `y` is `bytearray`,
+            and nonce is hex `str`
 
-        :param dvsni_key: Namedtuple with file, pem
-        :type dvsni_key: :class:`client.Client.Key`
+        :param dvsni_key: DVSNI key
+        :type dvsni_key: :class:`letsencrypt.client.client.Client.Key`
 
         :param list ll_addrs: list of list of addresses to apply
 
@@ -1388,8 +1389,7 @@ def enable_mod(mod_name):
 
     Both enables and restarts Apache so module is active.
 
-    :param mod_name: Name of the module to enable
-    :type mod_name: str
+    :param str mod_name: Name of the module to enable
 
     """
     try:
@@ -1411,7 +1411,8 @@ def check_ssl_loaded():
     """Checks to see if mod_ssl is loaded
 
     Currently uses apache2ctl to get loaded module list
-    TODO: This function is likely fragile to versions/distros
+
+    .. todo:: This function is likely fragile to versions/distros
 
     :returns: If ssl_module is included and active in Apache
     :rtype: bool
@@ -1491,8 +1492,7 @@ def get_file_path(vhost_path):
 
     Takes in Augeas path and returns the file name
 
-    :param vhost_path: Augeas virtual host path
-    :type vhost_path: str
+    :param str vhost_path: Augeas virtual host path
 
     :returns: filename of vhost
     :rtype: str
@@ -1537,8 +1537,7 @@ def strip_dir(path):
 def dvsni_get_cert_file(nonce):
     """Returns standardized name for challenge certificate.
 
-    :param nonce: hex form of nonce
-    :type nonce: str
+    :param str nonce: hex form of nonce
 
     :returns: certificate file name
     :rtype: str
@@ -1550,12 +1549,8 @@ def dvsni_get_cert_file(nonce):
 def get_config_text(nonce, ip_addrs, dvsni_key_file):
     """Chocolate virtual server configuration text
 
-    :param nonce: hex form of nonce
-    :type nonce: str
-
-    :param ip_addrs: addresses of challenged domain
-    :type ip_addrs: str
-
+    :param str nonce: hex form of nonce
+    :param str ip_addrs: addresses of challenged domain
     :param str dvsni_key_file: Path to key file
 
     :returns: virtual host configuration text
@@ -1580,11 +1575,8 @@ def get_config_text(nonce, ip_addrs, dvsni_key_file):
 def dvsni_gen_ext(dvsni_r, dvsni_s):
     """Generates z extension to be placed in certificate extension.
 
-    :param dvsni_r: DVSNI r value
-    :type dvsni_r: byte array
-
-    :param dvsni_s: DVSNI s value
-    :type dvsni_s: byte array
+    :param bytearray dvsni_r: DVSNI r value
+    :param bytearray dvsni_s: DVSNI s value
 
     result: returns z + CONFIG.INVALID_EXT
 
@@ -1597,7 +1589,7 @@ def dvsni_gen_ext(dvsni_r, dvsni_s):
 
 
 def main():
-    """ Main function used for quick testing purposes """
+    """Main function used for quick testing purposes"""
 
     config = ApacheConfigurator()
     logger.setLogger(logger.FileLogger(sys.stdout))

letsencrypt/client/client.py

@@ -37,11 +37,16 @@ class Client(object):
 
     def __init__(self, ca_server, cert_signing_request=CSR(None, None, None),
                  private_key=Key(None, None), use_curses=True):
-        """
+        """Initialize client.
 
         :param str ca_server: Certificate authority server
-        :param str cert_signing_request: Contents of the CSR
-        :param str private_key: Contents of the private key
+
+        :param cert_signing_request: Certificate Signing Request
+        :type cert_signing_request: :class:`CSR`
+
+        :param private_key: Private key
+        :type private_key: :class:`Key`
+
         :param bool use_curses: Use curses UI
 
         """

letsencrypt/client/crypto_util.py

@@ -27,7 +27,7 @@ def create_sig(msg, key_str, nonce=None, nonce_len=CONFIG.NONCE_SIZE):
 
     .. todo:: Change this over to M2Crypto... PKey
 
-    .. todo::Protect against crypto unicode errors... is this sufficient?
+    .. todo:: Protect against crypto unicode errors... is this sufficient?
         Do I need to escape?
 
     :param str key_str: Key in string form. Accepted formats

letsencrypt/scripts/main.py

@@ -105,8 +105,8 @@ def read_file(filename):
 
     :param str filename: Filename
 
-    :returns: File contents
-    :rtype: str
+    :returns: A tuple of filename and its contents
+    :rtype: tuple
 
     :raises argparse.ArgumentTypeError: File does not exist or is not readable.