From ed23290232658bbff97d23e3e749b192960f04dd Mon Sep 17 00:00:00 2001
From: Andrew Ittner <andrew.ittner@usa.net>
Date: Fri, 26 May 2017 20:57:14 -0700
Subject: [PATCH] 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      | 12 ++++--------
 certbot/display/ops.py |  9 +++++----
 docs/challenges.rst    |  3 +++
 docs/conf.py           |  1 +
 docs/contributing.rst  |  2 +-
 docs/index.rst         |  6 ++++++
 docs/packaging.rst     |  2 +-
 7 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/certbot/client.py b/certbot/client.py
index 13b35e164..af2868f6a 100644
--- a/certbot/client.py
+++ b/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.
diff --git a/certbot/display/ops.py b/certbot/display/ops.py
index ffd4947ad..57d2362fd 100644
--- a/certbot/display/ops.py
+++ b/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
     """
diff --git a/docs/challenges.rst b/docs/challenges.rst
index e45b9d852..c00cd3bdf 100644
--- a/docs/challenges.rst
+++ b/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.
diff --git a/docs/conf.py b/docs/conf.py
index 7b3f2026c..73df47dbd 100644
--- a/docs/conf.py
+++ b/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 ----------------------------------------------
 
diff --git a/docs/contributing.rst b/docs/contributing.rst
index e6275e1bc..c144a4f74 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -9,7 +9,7 @@ Developer Guide
 .. _getting_started:
 
 Getting Started
-=======
+===============
 
 Running a local copy of the client
 ----------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index 746080864..d2399d5d8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,12 @@ Welcome to the Certbot documentation!
 
    api
 
+.. toctree::
+   :hidden:
+
+   challenges
+   ciphers
+
 
 Indices and tables
 ==================
diff --git a/docs/packaging.rst b/docs/packaging.rst
index a60ce72d5..3b7e21ab3 100644
--- a/docs/packaging.rst
+++ b/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