diff --git a/README.rst b/README.rst
index ec7516f94..0863f7ece 100644
--- a/README.rst
+++ b/README.rst
@@ -25,9 +25,9 @@ Repository:
 
 * https://git.openstack.org/cgit/openstack-infra/jenkins-job-builder
 
-Cloning:
+Cloning::
 
-* git clone https://git.openstack.org/openstack-infra/jenkins-job-builder
+    git clone https://git.openstack.org/openstack-infra/jenkins-job-builder
 
 Patches are submitted via Gerrit at:
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1db175c05..6e09b560b 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -210,6 +210,12 @@ latex_documents = [
 # If false, no module index is generated.
 #latex_domain_indices = True
 
+# -- Options for linkcheck ----------------------------------------------------
+
+# If set, override pythons default socket timeout
+# testing has shown the default is too short so explicitly increase to 15 secs
+linkcheck_timeout = 15
+
 
 # -- Options for manual page output --------------------------------------------
 
diff --git a/jenkins_jobs/builder.py b/jenkins_jobs/builder.py
index d474877ea..8bd7c8661 100644
--- a/jenkins_jobs/builder.py
+++ b/jenkins_jobs/builder.py
@@ -464,7 +464,7 @@ class ModuleRegistry(object):
 
         :arg string plugin_name: Either the shortName or longName of a plugin
           as see in a query that looks like:
-          http://<jenkins-hostname>/pluginManager/api/json?pretty&depth=2
+          ``http://<jenkins-hostname>/pluginManager/api/json?pretty&depth=2``
 
         During a 'test' run, it is possible to override JJB's query to a live
         Jenkins instance by passing it a path to a file containing a YAML list
diff --git a/setup.cfg b/setup.cfg
index 98957a0c3..35d83e133 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -2,6 +2,7 @@
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+builders = html,man,linkcheck
 
 [metadata]
 name = jenkins-job-builder