Merge pull request #448 from kuba/docs

Various docstring fixes.

docs/plugins.rst

@@ -4,16 +4,16 @@ Plugins
 
 Let's Encrypt client supports dynamic discovery of plugins through the
 `setuptools entry points`_. This way you can, for example, create a
-custom implementation of
+custom implementation of `~letsencrypt.interfaces.IAuthenticator` or
-`~letsencrypt.interfaces.IAuthenticator` or the
+the `~letsencrypt.interfaces.IInstaller` without having to merge it
-'~letsencrypt.interfaces.IInstaller' without having to
+with the core upstream source code. An example is provided in
-merge it with the core upstream source code. An example is provided in
 ``examples/plugins/`` directory.
 
-Please be aware though that as this client is still in a developer-preview
+.. warning:: Please be aware though that as this client is still in a
-stage, the API may undergo a few changes. If you believe the plugin will be
+   developer-preview stage, the API may undergo a few changes. If you
-beneficial to the community, please consider submitting a pull request to the
+   believe the plugin will be beneficial to the community, please
-repo and we will update it with any necessary API changes.
+   consider submitting a pull request to the repo and we will update
+   it with any necessary API changes.
 
 .. _`setuptools entry points`:
   https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins

letsencrypt/auth_handler.py

@@ -53,12 +53,12 @@ class AuthHandler(object):
         """Retrieve all authorizations for challenges.
 
         :param set domains: Domains for authorization
-        :param bool best_effort: Whether or not all authorizations are required
+        :param bool best_effort: Whether or not all authorizations are
-            (this is useful in renewal)
+             required (this is useful in renewal)
 
-        :returns: tuple of lists of authorization resources. Takes the form of
+        :returns: tuple of lists of authorization resources. Takes the
-            (`completed`, `failed`)
+            form of (`completed`, `failed`)
-        rtype: tuple
+        :rtype: tuple
 
         :raises AuthorizationError: If unable to retrieve all
             authorizations

letsencrypt/interfaces.py

@@ -49,7 +49,7 @@ class IPluginFactory(zope.interface.Interface):
         """Inject argument parser options (flags).
 
         1. Be nice and prepend all options and destinations with
-        `~.option_namespace` and `~.dest_namespace`.
+        `~.common.option_namespace` and `~common.dest_namespace`.
 
         2. Inject options (flags) only. Positional arguments are not
         allowed, as this would break the CLI.

letsencrypt_nginx/obj.py

@@ -5,22 +5,25 @@ from letsencrypt_apache.obj import Addr as ApacheAddr
 
 
 class Addr(ApacheAddr):
-    """Represents an Nginx address, i.e. what comes after the 'listen'
+    r"""Represents an Nginx address, i.e. what comes after the 'listen'
     directive.
 
-    According to http://nginx.org/en/docs/http/ngx_http_core_module.html#listen,
+    According to the `documentation`_, this may be address[:port], port,
-    this may be address[:port], port, or unix:path. The latter is ignored here.
+    or unix:path. The latter is ignored here.
 
-    The default value if no directive is specified is *:80 (superuser) or
+    The default value if no directive is specified is \*:80 (superuser)
-    *:8000 (otherwise). If no port is specified, the default is 80. If no
+    or \*:8000 (otherwise). If no port is specified, the default is
-    address is specified, listen on all addresses.
+    80. If no address is specified, listen on all addresses.
 
-    .. todo:: Old-style nginx configs define SSL vhosts in a separate block
+    .. _documentation:
-    instead of using 'ssl' in the listen directive
+       http://nginx.org/en/docs/http/ngx_http_core_module.html#listen
+
+    .. todo:: Old-style nginx configs define SSL vhosts in a separate
+              block instead of using 'ssl' in the listen directive.
 
     :param str addr: addr part of vhost address, may be hostname, IPv4, IPv6,
-        "", or "*"
+        "", or "\*"
-    :param str port: port number or "*" or ""
+    :param str port: port number or "\*" or ""
     :param bool ssl: Whether the directive includes 'ssl'
     :param bool default: Whether the directive includes 'default_server'