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>
2019-12-20 11:02:15 -05:00 · 2019-12-20 11:02:15 -05:00 · 7b00932d2c
commit 7b00932d2c
parent 497198a252
13 changed files with 51 additions and 39 deletions
--- a/.zuul.yaml
+++ b/.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
--- a/doc/source/conf.py
+++ b/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
--- a/doc/source/quick-start.rst
+++ b/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/
-.. _pypi: https://pypi.python.org/pypi/jenkins-job-builder/
-.. _examples: http://git.openstack.org/cgit/openstack-infra/jenkins-job-builder/tree/tests
+.. _repository: https://opendev.org/jjb/jenkins-job-builder/
+.. _pypi: https://pypi.org/project/jenkins-job-builder/
+.. _examples: https://opendev.org/jjb/jenkins-job-builder/src/branch/master/tests


 .. _use-case-1:
--- a/jenkins_jobs/modules/builders.py
+++ b/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
-    <Artifactory+Plugin>`.
+    Requires the Jenkins `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/\
-        Analyzing+with+SonarQube+Scanner+for+Jenkins\
-        #AnalyzingwithSonarQubeScannerforJenkins-\
-        AnalyzingwiththeSonarQubeScanner>`_
+    <https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-jenkins>`_

    :arg str sonar-name: Name of the Sonar installation.
    :arg str sonar-scanner: Name of the Sonar Scanner.
--- a/jenkins_jobs/modules/parameters.py
+++ b/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)
--- a/jenkins_jobs/modules/project_multijob.py
+++ b/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::

--- a/jenkins_jobs/modules/properties.py
+++ b/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:

--- a/jenkins_jobs/modules/publishers.py
+++ b/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/\
-        Analyzing+with+SonarQube+Scanner+for+Jenkins>`_
+    <https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-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>`.
--- a/jenkins_jobs/modules/scm.py
+++ b/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
-            * **kilnhg** - https://www.fogcreek.com/kiln/
+            * **hgweb** - https://www.mercurial-scm.org/repo/hg/help/hgweb
+            * **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)

--- a/jenkins_jobs/modules/triggers.py
+++ b/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/
-                 access-control.html#categories>`_
+                 <https://gerrit-review.googlesource.com/Documentation/
+                 access-control.html#access_categories>`_

               * **approval-value** -- Approval value for the comment added.
         * **comment-added-contains-event** (`dict`) -- Trigger on comment
--- a/jenkins_jobs/modules/wrappers.py
+++ b/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 '')
--- a/jenkins_jobs/modules/zuul.py
+++ b/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
--- a/tox.ini
+++ b/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}