Enable docs-linkcheck

This toxenv will allow us to flag URLs that no longer work. We
also switch from using old style setup.py build_sphinx to the
newer sphinx-build command.

Change-Id: I62f42918814fb6eea4876e0d22c6bccddf86a826
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

.zuul.yaml

@@ -7,6 +7,12 @@
       - jjb/jenkins-job-builder
     voting: true
 
+- job:
+    name: jjb-tox-docs-linkcheck
+    parent: tox
+    vars:
+      tox_envlist: docs-linkcheck
+
 - project:
     templates:
       - docs-on-readthedocs
@@ -17,4 +23,5 @@
     check:
       jobs:
         - jjb-tox-cross-python-jenkins
+        - jjb-tox-docs-linkcheck
         - tox-cover

doc/source/conf.py

@@ -276,3 +276,10 @@ extlinks = {
     "jenkins-wiki": ("https://wiki.jenkins.io/display/JENKINS/%s", None),
     "jenkins-plugins": ("https://plugins.jenkins.io/%s", None),
 }
+
+linkcheck_ignore = [
+    r"https?:\/\/.*example\.org",
+    # gitorious is read-only archived with an expired certificate
+    "https://gitorious.org",
+]
+linkcheck_timeout = 300

doc/source/quick-start.rst

@@ -12,9 +12,9 @@ job definitions we use to test JJB.
 
 Usage of the commands below assumes that you are at the root of the cloned directory.
 
-.. _repository: http://git.openstack.org/cgit/openstack-infra/jenkins-job-builder/
+.. _repository: https://opendev.org/jjb/jenkins-job-builder/
-.. _pypi: https://pypi.python.org/pypi/jenkins-job-builder/
+.. _pypi: https://pypi.org/project/jenkins-job-builder/
-.. _examples: http://git.openstack.org/cgit/openstack-infra/jenkins-job-builder/tree/tests
+.. _examples: https://opendev.org/jjb/jenkins-job-builder/src/branch/master/tests
 
 
 .. _use-case-1:

jenkins_jobs/modules/builders.py

@@ -115,7 +115,7 @@ def copyartifact(registry, xml_parent, data):
     Artifact plugin <Copy+Artifact+Plugin>`.
 
     Please note using the multijob-build for which-build argument requires
-    the :jenkins-wiki:`Multijob plugin <Multijob+Plugin>`
+    the :jenkins-plugins:`Multijob plugin <jenkins-multijob-plugin>`
 
     :arg str project: Project to copy from
     :arg str filter: what files to copy
@@ -956,7 +956,7 @@ def kmap(registry, xml_parent, data):
     :arg str password:  Password for the KMAP user uploading/publishing
         applications (required)
     :arg str url: KMAP's url. This url must always end with "/kmap-client/".
-        For example: http://testing.keivox.com/kmap-client/ (required)
+        For example: http://testing.example.org/kmap-client/ (required)
     :arg str categories: Categories' names. If you want to add the application
         to more than one category, write the categories between commas.
         (required)
@@ -1803,8 +1803,8 @@ def maven_builder(registry, xml_parent, data):
 
     Allows your build jobs to deploy artifacts automatically to Artifactory.
 
-    Requires the Jenkins :jenkins-wiki:`Artifactory Plugin
+    Requires the Jenkins `Artifactory Plugin
-    <Artifactory+Plugin>`.
+    <https://www.jfrog.com/confluence/display/RTF/Jenkins+Artifactory+Plug-in>`_.
 
     :arg str name: Name of maven installation from the configuration (required)
     :arg str pom: Location of pom.xml (default 'pom.xml')
@@ -1940,7 +1940,7 @@ def maven_target(registry, xml_parent, data):
 def multijob(registry, xml_parent, data):
     """yaml: multijob
     Define a multijob phase. Requires the Jenkins
-    :jenkins-wiki:`Multijob Plugin <Multijob+Plugin>`.
+    :jenkins-plugins:`Multijob Plugin <jenkins-multijob-plugin>`.
 
     This builder may only be used in
     :py:class:`jenkins_jobs.modules.project_multijob.MultiJob` projects.
@@ -3090,10 +3090,7 @@ def sonar(registry, xml_parent, data):
     """yaml: sonar
     Invoke standalone Sonar analysis.
     Requires the Jenkins `Sonar Plugin.
-    <http://docs.sonarqube.org/display/SCAN/\
+    <https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-jenkins>`_
-        Analyzing+with+SonarQube+Scanner+for+Jenkins\
-        #AnalyzingwithSonarQubeScannerforJenkins-\
-        AnalyzingwiththeSonarQubeScanner>`_
 
     :arg str sonar-name: Name of the Sonar installation.
     :arg str sonar-scanner: Name of the Sonar Scanner.

jenkins_jobs/modules/parameters.py

@@ -585,7 +585,7 @@ def svn_tags_param(registry, xml_parent, data):
             name: BRANCH_NAME
             default: release
             description: A parameter named BRANCH_NAME default is release
-            url: http://svn.example.com/repo
+            url: http://svn.example.org/repo
             filter: [A-za-z0-9]*
     """
     pdef = base_param(
@@ -800,7 +800,7 @@ def matrix_combinations_param(registry, xml_parent, data):
     """yaml: matrix-combinations
     Matrix combinations parameter
     Requires the Jenkins :jenkins-wiki:`Matrix Combinations Plugin
-    <Matrix+Combinations+Plugin>`.
+    <Matrix+Configuration+Parameter+Plugin>`.
 
     :arg str name: the name of the parameter
     :arg str description: a description of the parameter (optional)

jenkins_jobs/modules/project_multijob.py

@@ -21,7 +21,7 @@ the :ref:`Job` definition.
 This project type may use :py:func:`jenkins_jobs.modules.builders.multijob` \
 builders.
 
-Requires the Jenkins :jenkins-wiki:`Multijob Plugin <Multijob+Plugin>`.
+Requires the Jenkins :jenkins-plugins:`Multijob Plugin <jenkins-multijob-plugin>`.
 
 Example::
 

jenkins_jobs/modules/properties.py

@@ -823,7 +823,7 @@ def zeromq_event(registry, xml_parent, data):
     (start, complete, finish) to a ZMQ PUB socket.
 
     Requires the Jenkins `ZMQ Event Publisher.
-    <https://git.openstack.org/cgit/openstack-infra/zmq-event-publisher>`_
+    <https://opendev.org/x/zmq-event-publisher>`_
 
     Example:
 

jenkins_jobs/modules/publishers.py

@@ -1451,7 +1451,7 @@ def hp_alm(registry, xml_parent, data):
     Publish test results to HP-ALM.
 
     Requires the Jenkins :jenkins-wiki:`Micro Focus Application Automation
-    Tools <Micro+Focus+Application+Automation+Tools)>`.
+    Tools <Micro+Focus+Application+Automation+Tools>`.
 
     :arg str server-name: The name of the ALM Server. (required)
     :arg str credentials-id: credentials-id of the user (default '')
@@ -1483,7 +1483,7 @@ def hp_alm(registry, xml_parent, data):
         for Junit Plugin, ``**/testng-results.xml`` to find
         testing result file for TestNG plugin. (required)
     :arg str jenkins-server-url: The HTTP URL of the Jenkins Server,
-        form example, http://myjenkinsserver.test.com:8080 . (optional)
+        form example, http://jenkins.example.org:8080 . (optional)
 
     Minimal example using defaults:
 
@@ -3146,8 +3146,7 @@ def sonar(registry, xml_parent, data):
     """yaml: sonar
     Sonar plugin support.
     Requires the Jenkins `Sonar Plugin.
-    <http://docs.sonarqube.org/display/SONAR/\
+    <https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-jenkins>`_
-        Analyzing+with+SonarQube+Scanner+for+Jenkins>`_
 
     :arg str installation-name: name of the Sonar instance to use (optional)
     :arg str jdk: JDK to use (inherited from the job if omitted). (optional)
@@ -5310,7 +5309,7 @@ def gitlab_message(registry, xml_parent, data):
 def zulip(registry, xml_parent, data):
     """yaml: zulip
     Set build status on zulip.
-    Requires the Jenkins :jenkins-wiki:`Humbug Plugin <Humbug+Plugin>`.
+    Requires the Jenkins :jenkins-wiki:`Humbug Plugin <Deprecated%3A+Humbug+Plugin>`.
 
     Example:
 
@@ -5375,7 +5374,7 @@ def stash(registry, xml_parent, data):
     notify Atlassian Stash after job completes.
 
     Requires the Jenkins :jenkins-wiki:`StashNotifier Plugin
-    <StashNotifier+Plugin>`.
+    <Bitbucket+%28Stash%29+Notifier+Plugin>`.
 
     :arg string url: Base url of Stash Server (default "")
     :arg string username: Username of Stash Server (default "")
@@ -7537,7 +7536,7 @@ def slack(registry, xml_parent, data):
 
 def phabricator(registry, xml_parent, data):
     """yaml: phabricator
-    Integrate with `Phabricator <http://phabricator.org/>`_
+    Integrate with `Phabricator <https://www.phacility.com/>`_
 
     Requires the Jenkins :jenkins-wiki:`Phabricator Plugin
     <Phabricator+Differential+Plugin>`.

jenkins_jobs/modules/scm.py

@@ -225,17 +225,17 @@ def git(registry, xml_parent, data):
             * **fisheye** - https://www.atlassian.com/software/fisheye
             * **gitblit** - http://gitblit.com/
             * **githubweb** - https://github.com/
-            * **gitiles** - https://code.google.com/p/gitiles/
+            * **gitiles** - https://code.google.com/archive/p/gitiles/
             * **gitlab** - https://about.gitlab.com/
             * **gitlist** - http://gitlist.org/
             * **gitoriousweb** - https://gitorious.org/
             * **gitweb** - https://git-scm.com/docs/gitweb
-            * **kiln** - https://www.fogcreek.com/kiln/
+            * **kiln** - https://www.fogbugz.com/version-control
             * **microsoft\-tfs\-2013** - |tfs_2013|
-            * **phabricator** - http://phabricator.org/
+            * **phabricator** - https://www.phacility.com/
             * **redmineweb** - http://www.redmine.org/
             * **rhodecode** - https://rhodecode.com/
-            * **stash** - https://www.atlassian.com/software/bitbucket/server
+            * **stash** - https://www.atlassian.com/software/bitbucket/enterprise/data-center
             * **viewgit** - http://viewgit.fealdia.org/
     :arg str browser-url: url for the repository browser (required if browser
         is not 'auto', no default)
@@ -326,7 +326,7 @@ def git(registry, xml_parent, data):
     .. literalinclude:: /../../tests/scm/fixtures/git001.yaml
 
     .. |tfs_2013| replace::
-        https://www.visualstudio.com/en-us/products/tfs-overview-vs.aspx
+        https://azure.microsoft.com/en-us/services/devops/server
 
     """
     logger = logging.getLogger("%s:git" % __name__)
@@ -1285,8 +1285,8 @@ def hg(self, xml_parent, data):
             * **bitbucketweb** - https://bitbucket.org/
             * **fisheye** - https://www.atlassian.com/software/fisheye
             * **googlecode** - https://code.google.com/
-            * **hgweb** - https://www.selenic.com/hg/help/hgweb
+            * **hgweb** - https://www.mercurial-scm.org/repo/hg/help/hgweb
-            * **kilnhg** - https://www.fogcreek.com/kiln/
+            * **kilnhg** - https://www.fogbugz.com/version-control
             * **rhodecode** - https://rhodecode.com/ (versions >= 1.2)
             * **rhodecode-pre-1.2.0** - https://rhodecode.com/ (versions < 1.2)
 

jenkins_jobs/modules/triggers.py

@@ -296,8 +296,8 @@ def gerrit(registry, xml_parent, data):
                * **approval-category** (`str`) -- Approval (verdict) category
                  (for example 'APRV', 'CRVW', 'VRIF' -- see `Gerrit access
                  control
-                 <http://gerrit.googlecode.com/svn/documentation/2.1/
+                 <https://gerrit-review.googlesource.com/Documentation/
-                 access-control.html#categories>`_
+                 access-control.html#access_categories>`_
 
                * **approval-value** -- Approval value for the comment added.
          * **comment-added-contains-event** (`dict`) -- Trigger on comment

jenkins_jobs/modules/wrappers.py

@@ -2415,7 +2415,7 @@ def artifactory_maven(registry, xml_parent, data):
     :jenkins-wiki:`Artifactory Plugin <Artifactory+Plugin>`
 
     :arg str url: URL of the Artifactory server. e.g.
-        https://www.jfrog.com/artifactory/ (default '')
+        https://jfrog.com/artifactory/ (default '')
     :arg str name: Artifactory user with permissions use for
         connected to the selected Artifactory Server
         (default '')
@@ -2458,7 +2458,7 @@ def artifactory_generic(registry, xml_parent, data):
     :jenkins-wiki:`Artifactory Plugin <Artifactory+Plugin>`
 
     :arg str url: URL of the Artifactory server. e.g.
-        https://www.jfrog.com/artifactory/ (default '')
+        https://jfrog.com/artifactory/ (default '')
     :arg str name: Artifactory user with permissions use for
         connected to the selected Artifactory Server
         (default '')
@@ -2590,7 +2590,7 @@ def artifactory_maven_freestyle(registry, xml_parent, data):
     Requires :jenkins-wiki:`Artifactory Plugin <Artifactory+Plugin>`
 
     :arg str url: URL of the Artifactory server. e.g.
-        https://www.jfrog.com/artifactory/ (default '')
+        https://jfrog.com/artifactory/ (default '')
     :arg str name: Artifactory user with permissions use for
         connected to the selected Artifactory Server (default '')
     :arg str release-repo-key: Release repository name (default '')

jenkins_jobs/modules/zuul.py

@@ -17,7 +17,7 @@ The Zuul module adds jobs parameters to manually run a build as Zuul would
 have. It is entirely optional, Zuul 2.0+ pass the parameters over Gearman.
 
 .. _expected by Zuul: \
-http://docs.openstack.org/infra/zuul/launchers.html#zuul-parameters
+https://opendev.org/zuul/zuul/src/tag/2.6.0/doc/source/launchers.rst#zuul-parameters
 """
 
 import itertools

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 2.2
-envlist = linters, docs, py34, py35, py36, py27, cover
+envlist = linters, docs, docs-linkcheck, py34, py35, py36, py27, cover
 skip_missing_interpreters = true
 # custom vars (no meaning to tox)
 install_test_deps = pip install -q -r test-requirements.txt
@@ -76,13 +76,15 @@ commands = jenkins-jobs test -o .test/new/out/ .test/new/config/
 [testenv:docs]
 commands =
     {[tox]install_test_deps}
-    python setup.py build_sphinx {posargs}
+    sphinx-build -n -b html -d doc/build/doctrees doc/source doc/build/html
 
 [testenv:docs-linkcheck]
 # If you are behind a proxy, for this test to work you will need to set
 # TOX_TESTENV_PASSENV="http_proxy https_proxy no_proxy ..." to pass
 # through the proxy environment settings to be able to validate any urls.
-commands = python setup.py build_sphinx -b linkcheck
+commands =
+    {[tox]install_test_deps}
+    sphinx-build -n -b linkcheck -d doc/build/doctrees doc/source doc/build/linkcheck
 
 [testenv:venv]
 commands = {posargs}