Check external documentation links are valid

Use sphinx's linkcheck builder to validate any external links.

Fix the broken links by converting the example link to a code segment
and correcting the link referencing the cgit mirror for the git clone
instructions.

Change-Id: Ic6236e250b7af5c7c000af1e67fb69dd720ad6d8

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:
 

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 --------------------------------------------
 

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

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