[IMP] Improve documentation & compat with Sphinx

cfssl/__init__.py

@@ -2,6 +2,18 @@
 # Copyright 2016 LasLabs Inc.
 # License MIT (https://opensource.org/licenses/MIT).
 
+""" This library allows you to interact with a remote CFSSL server using Python.
+
+CFSSL is CloudFlare's open source toolkit for everything TLS/SSL. CFSSL is used by
+CloudFlare for their internal Certificate Authority infrastructure and for all of
+their TLS certificates.
+
+* `Read more on the CloudFlare blog
+  <https://blog.cloudflare.com/introducing-cfssl/>`_.
+* `View the CFSSL source
+  <https://github.com/cloudflare/cfssl>`_.
+"""
+
 # API
 from .cfssl import CFSSL
 

cfssl/models/certificate_request.py

@@ -14,13 +14,13 @@ def __init__(self, common_name, names=None, hosts=None, key=None):
         """ Initialize a new CertificateRequest.
 
         Args:
-            common_name (:obj:`str`): The fully qualified domain name for the
+            common_name (str): The fully qualified domain name for the
                 server. This must be an exact match.
-            names (:type:`iter` of :obj:`cfssl.SubjectInfo`, optional):
+            names (tuple of SubjectInfo, optional):
                 Subject Information to be added to the request.
-            hosts (:type:`iter` of :obj:`cfssl.Host`, optional): Hosts
+            hosts (tuple of Host, optional): Hosts
                 to be added to the request.
-            key (:obj:`cfssl.ConfigKey`, optional): Key configuration
+            key (ConfigKey, optional): Key configuration
                 for the request.
         """
         self.common_name = common_name

cfssl/models/config_client.py

@@ -13,13 +13,13 @@ def __init__(self, sign_policy_default,
         """ Initialize a new Client Configuration.
 
         Args:
-            sign_policy_default (:obj:`cfssl.PolicySign`): Default signing
+            sign_policy_default (PolicySign): Default signing
                 policy for client to use.
-            sign_policies_add (:type:`iter` of :obj:`cfssl.PolicySign`):
+            sign_policies_add (tuple of PolicySign):
                 Additional signing policies to use for the client.
-            auth_policies (:type:`iter` of :obj:`cfssl.PolicyAuth`): Auth
+            auth_policies (tuple of PolicyAuth): Auth
                 policies for the client.
-            remotes (:type:`iter` of :obj:`cfssl.Host`): Remote hosts that
+            remotes (tuple of Host): Remote hosts that
                 client trusts.
         """
         super(ConfigClient, self).__init__(

cfssl/models/config_key.py

@@ -13,9 +13,9 @@ def __init__(self, algorithm=DEFAULT_ALGORITHM,
         """ Initialize a new Client Configuration.
 
         Args:
-            algorithm (:obj:`str`, optional): Algorithm to use for key, one of
+            algorithm (str, optional): Algorithm to use for key, one of
                 ``rsa`` or ``ecdsa``. Defaults to ``rsa``.
-            strength (:obj:`int`, optional): Key bit strength. Defaults to
+            strength (int, optional): Key bit strength. Defaults to
                 ``4096``.
         """
         self.algorithm = algorithm

cfssl/models/config_mixer.py

@@ -10,11 +10,11 @@ def __init__(self, sign_policy_default, sign_policies_add, auth_policies):
         """ Initialize a new General Configuration for Server or Client.
 
         Args:
-            sign_policy_default (:obj:`cfssl.PolicySign`): Default signing
+            sign_policy_default (PolicySign): Default signing
                 policy for entity to use.
-            sign_policies_add (:type:`iter` of :obj:`cfssl.PolicySign`):
+            sign_policies_add (tuple of PolicySign):
                 Additional signing policies to use for the entity.
-            auth_policies (:type:`iter` of :obj:`cfssl.PolicyAuth`): Auth
+            auth_policies (tuple of PolicyAuth): Auth
                 policies for the entity.
         """
         self.sign_policy = sign_policy_default

cfssl/models/host.py

@@ -10,9 +10,9 @@ def __init__(self, name, host, port=None):
         """ Initialize a new Client Configuration.
 
         Args:
-            name (:obj:`str`): Canonical name of host/remote.
-            host (:obj:`str`): Advertised host name or IP for host.
-            port (:obj:`int`, optional): Port number advertised by host, if
+            name (str): Canonical name of host/remote.
+            host (str): Advertised host name or IP for host.
+            port (int, optional): Port number advertised by host, if
                 any.
         """
         self.name = name

cfssl/models/policy_auth.py

@@ -10,9 +10,9 @@ def __init__(self, name, key, key_type='standard'):
         """ Initialize a new Authentication Policy.
 
         Args:
-            name (:obj:`str`): Canonical name for policy.
-            key (:obj:`str`): Key/password data.
-            key_type (:obj:`str`): Type of key. Currently only ``standard`` is
+            name (str): Canonical name for policy.
+            key (str): Key/password data.
+            key_type (str): Type of key. Currently only ``standard`` is
                 supported.
         """
         self.name = name

cfssl/models/policy_sign.py

@@ -13,12 +13,12 @@ def __init__(self, name, usage_policies, auth_policy,
         """ Initialize a new Signing Policy.
 
         Args:
-            name (:obj:`str`): Canonical name for policy.
-            usage_policies (:type:`iter` of :obj:`cfssl.PolicyUse`): Usage
+            name (str): Canonical name for policy.
+            usage_policies (tuple of PolicyUser): Usage
                 policies that should apply to this signing policy.
-            auth_policy (:obj:`obj.PolicyAuth`): Authentication policy that
+            auth_policy (PolicyAuth): Authentication policy that
                 should apply to this signing policy.
-            expire_delta  (:obj:`datetime.timedelta`): Delta representing when
+            expire_delta  (timedelta): Delta representing when
                 the signature should expire.
         """
         self.name = name

cfssl/models/policy_use.py

@@ -10,8 +10,8 @@ def __init__(self, name, code):
         """ Initialize a new Use Policy.
 
         Args:
-            name (:obj:`str`): Canonical name for policy.
-            code (:obj:`str`): CFSSL use code that policy applies to.
+            name (str): Canonical name for policy.
+            code (str): CFSSL use code that policy applies to.
         """
         self.name = name
         self.code = code

cfssl/models/subject_info.py

@@ -10,12 +10,12 @@ def __init__(self, org_name, org_unit, city, state, country):
         """ Initialize a new Subject Information.
 
         Args:
-            org_name (:obj:`str`): The full legal name of the organization. Do
+            org_name (str): The full legal name of the organization. Do
                 not abbreviate.
-            org_unit (:obj:`str`): Section of the organization.
-            city (:obj:`str`): The city where the organization is legally
+            org_unit (str): Section of the organization.
+            city (str): The city where the organization is legally
                 located.
-            country (:obj:`str`): The two letter ISO abbreviation for the
+            country (str): The two letter ISO abbreviation for the
                 country.
         """
         self.org_name = org_name