Clean up Sphinx errors (#4706)

Also minor copyedits, suppress unhelpful errors, mark files that should
*not* be in the TOC as hidden.

certbot/client.py

@@ -493,15 +493,11 @@ class Client(object):
     def apply_enhancement(self, domains, enhancement, options=None):
         """Applies an enhancement on all domains.
 
-        :param domains: list of ssl_vhosts
-        :type list of str
+        :param list domains: list of ssl_vhosts (as strings)
+        :param str enhancement: name of enhancement, e.g. ensure-http-header
+        :param str options: options to enhancement, e.g. Strict-Transport-Security
 
-        :param enhancement: name of enhancement, e.g. ensure-http-header
-        :type str
-
-        .. note:: when more options are need make options a list.
-        :param options: options to enhancement, e.g. Strict-Transport-Security
-        :type str
+            .. note:: When more `options` are needed, make options a list.
 
         :raises .errors.PluginError: If Enhancement is not supported, or if
             there is any other problem with the enhancement.

certbot/display/ops.py

@@ -324,8 +324,8 @@ def validated_input(validator, *args, **kwargs):
     :param callable validator: A method which will be called on the
         supplied input. If the method raises a `errors.Error`, its
         text will be displayed and the user will be re-prompted.
-    :param list *args: Arguments to be passed to `~certbot.interfaces.IDisplay.input`
-    :param dict **kwargs: Arguments to be passed to `~certbot.interfaces.IDisplay.input`
+    :param list `*args`: Arguments to be passed to `~certbot.interfaces.IDisplay.input`.
+    :param dict `**kwargs`: Arguments to be passed to `~certbot.interfaces.IDisplay.input`.
     :return: as `~certbot.interfaces.IDisplay.input`
     :rtype: tuple
     """
@@ -339,8 +339,9 @@ def validated_directory(validator, *args, **kwargs):
     :param callable validator: A method which will be called on the
         supplied input. If the method raises a `errors.Error`, its
         text will be displayed and the user will be re-prompted.
-    :param list *args: Arguments to be passed to `~certbot.interfaces.IDisplay.directory_select`
-    :param dict **kwargs: Arguments to be passed to `~certbot.interfaces.IDisplay.directory_select`
+    :param list `*args`: Arguments to be passed to `~certbot.interfaces.IDisplay.directory_select`.
+    :param dict `**kwargs`: Arguments to be passed to
+        `~certbot.interfaces.IDisplay.directory_select`.
     :return: as `~certbot.interfaces.IDisplay.directory_select`
     :rtype: tuple
     """

docs/challenges.rst

@@ -1,3 +1,6 @@
+Challenges
+==========
+
 Digital certificates can only be issued to people who are entitled to them. For example, assuming you don't run google.com, you're not entitled to a certificate for it. Nor is someone else entitled to receive a certificate for your web site.
 
 In order to receive a certificate from Let's Encrypt certificate authority (CA), you have to prove your control over each of the domain names that will be listed in the certificate. You can do so by making certain publicly-visible changes, proving that the person who's requested a particular certificate is the same person who controls the site(s) that the certificate will refer to.

docs/conf.py

@@ -119,6 +119,7 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+suppress_warnings = ['image.nonlocal_uri']
 
 # -- Options for HTML output ----------------------------------------------
 

docs/contributing.rst

@@ -9,7 +9,7 @@ Developer Guide
 .. _getting_started:
 
 Getting Started
-=======
+===============
 
 Running a local copy of the client
 ----------------------------------

docs/index.rst

@@ -16,6 +16,12 @@ Welcome to the Certbot documentation!
 
    api
 
+.. toctree::
+   :hidden:
+
+   challenges
+   ciphers
+
 
 Indices and tables
 ==================

docs/packaging.rst

@@ -51,7 +51,7 @@ From our official releases:
 From ``master``: https://aur.archlinux.org/packages/certbot-git
 
 Debian (and its derivatives, including Ubuntu)
-------
+----------------------------------------------
 
 - https://packages.debian.org/sid/certbot
 - https://packages.debian.org/sid/python-certbot