Fix: Update sphinx version pin, fix warnings

Sphinx was pinned to >1.5.0 <=1.7.0 4 years ago. It is now on v4.4.0,
and we're seeing an incompatibility with the latest version of jinja2.

Along with updating the Sphinx version, this also includes fixes for
several warnings generated in the latest version:
  * Outdated docs due to the removal of the "parser" param from
    Base.get_xml
  * Class lookup issues
  * External links for which we have extlinks defined
  * Deprated PyModulelevel is replaced by PyFunction
  * sphinx.ext.autodoc.Documenter.get_doc signature changed

Signed-off-by: Eric Ball <eball@linuxfoundation.org>
Change-Id: Iba65fb724f098f3e4a0b20f2a183cb2ea3c450ea

.zuul.yaml

@@ -1,7 +1,7 @@
 - job:
     name: jjb-tox-cross-python-jenkins
     description: Tests compatibility with master branch of python-jenkins
-    parent: tox-py27
+    parent: tox-py38
     required-projects:
       - jjb/python-jenkins
       - jjb/jenkins-job-builder
@@ -16,8 +16,6 @@
 - project:
     templates:
       - docs-on-readthedocs
-      - openstack-python-jobs-no-constraints
-      - openstack-python35-jobs-no-constraints
       - openstack-python36-jobs-no-constraints
       - openstack-python37-jobs-no-constraints
       - openstack-python38-jobs-no-constraints

doc/source/extending.rst

@@ -29,11 +29,10 @@ step.  All of the YAML to XML functions in Jenkins Job Builder have
 the same signature:
 
 .. _component_interface:
-.. py:function:: component(parser, xml_parent, data)
+.. py:function:: component(xml_parent, data)
   :noindex:
 
-  :arg YAMLParser parser: the jenkins jobs YAML parser
-  :arg Element xml_parent: this attribute's parent XML element
+  :arg class:`xml.etree.ElementTree` xml_parent: this attribute's parent XML element
   :arg dict data: the YAML data structure for this attribute and below
 
 The function is expected to examine the YAML data structure and create

jenkins_jobs/modules/base.py

@@ -68,8 +68,7 @@ class Base(object):
         Element objects and add them to the xml_parent.  The YAML data
         structure must not be modified.
 
-        :arg YAMLParser parser: the global YAML Parser
-        :arg Element xml_parent: the parent XML element
+        :arg class:`xml.etree.ElementTree` xml_parent: the parent XML element
         :arg dict data: the YAML data structure
         """
 

jenkins_jobs/modules/builders.py

@@ -1256,7 +1256,7 @@ def system_groovy(registry, xml_parent, data):
     :arg str bindings: Define variable bindings (in the properties file
         format). Specified variables can be addressed from the script.
         (optional)
-    :arg (list str) class-path: List of script class paths.
+    :arg list class-path: List of script class paths.
         (optional)
 
     Examples:

jenkins_jobs/modules/publishers.py

@@ -2028,7 +2028,7 @@ def findbugs(registry, xml_parent, data):
     FindBugs reporting for builds
 
     Requires the Jenkins FindBugs Plugin
-    (https://github.com/jenkinsci/findbugs-plugin).
+    (:jenkins-github:`findbugs-plugin`).
 
     :arg str pattern: specifies the generated raw FindBugs XML report files,
         such as \*\*/findbugs.xml or \*\*/findbugsXml.xml. (default '')
@@ -2096,7 +2096,7 @@ def checkstyle(registry, xml_parent, data):
     Publish trend reports with Checkstyle.
 
     Requires the Jenkins Checkstyle Plugin
-    (https://github.com/jenkinsci/checkstyle-plugin).
+    (:jenkins-github:`checkstyle-plugin`).
 
     The checkstyle component accepts a dictionary with the
     following values:
@@ -3307,7 +3307,7 @@ def cigame(registry, xml_parent, data):
     This plugin introduces a game where users get points
     for improving the builds.
     Requires the Jenkins Continuous Integration Game
-    plugin (https://github.com/jenkinsci/ci-game-plugin).
+    plugin (:jenkins-github:`ci-game-plugin`).
 
     Example:
 
@@ -4773,7 +4773,7 @@ def warnings(registry, xml_parent, data):
     in log files.
 
     Requires the Jenkins Warnings Plugin
-    (https://github.com/jenkinsci/warnings-plugin).
+    (:jenkins-github:`warnings-plugin`).
 
     :arg list console-log-parsers: The parser to use to scan the console
         log (default '')
@@ -6223,7 +6223,7 @@ def pmd(registry, xml_parent, data):
     """yaml: pmd
     Publish trend reports with PMD.
 
-    Requires the Jenkins PMD Plugin (https://github.com/jenkinsci/pmd-plugin).
+    Requires the Jenkins PMD Plugin (:jenkins-github:`pmd-plugin`).
 
     The PMD component accepts a dictionary with the following values:
 
@@ -6336,7 +6336,7 @@ def dry(registry, xml_parent, data):
     """yaml: dry
     Publish trend reports with DRY.
 
-    Requires the Jenkins DRY Plugin (https://github.com/jenkinsci/dry-plugin).
+    Requires the Jenkins DRY Plugin (:jenkins-github:`dry-plugin`).
 
     The DRY component accepts a dictionary with the following values:
 
@@ -8055,7 +8055,7 @@ def tasks(registry, xml_parent, data):
     Scans the workspace files for open tasks and generates a trend report.
 
     Requires the Jenkins Task Scanner Plugin
-    (https://github.com/jenkinsci/tasks-plugin).
+    (:jenkins-github:`tasks-plugin`).
 
     :arg list files-to-scan: Fileset includes setting that specifies the
         workspace files to scan for tasks, such as ``**/*.java``. Basedir of

jenkins_jobs/modules/reporters.py

@@ -77,7 +77,7 @@ def findbugs(registry, xml_parent, data):
     FindBugs reporting for builds
 
     Requires the Jenkins FindBugs Plugin
-    (https://github.com/jenkinsci/findbugs-plugin).
+    (:jenkins-github:`findbugs-plugin`).
 
     :arg bool rank-priority: Use rank as priority (default false)
     :arg str include-files: Comma separated list of files to include.

jenkins_jobs/modules/scm.py

@@ -1174,7 +1174,7 @@ def tfs(registry, xml_parent, data):
     Specifies the Team Foundation Server repository for this job.
 
     Requires the Jenkins Team Foundation Server Plugin
-    (https://github.com/jenkinsci/tfs-plugin).
+    (:jenkins-github:`tfs-plugin`).
 
     **NOTE**: TFS Password must be entered manually on the project if a
     user name is specified. The password will be overwritten with an empty

jenkins_jobs/modules/triggers.py

@@ -626,9 +626,7 @@ def gerrit(registry, xml_parent, data):
 
         .. deprecated:: 3.5.0  Supported for Gerrit Trigger Plugin versions
             < 2.14.0. See
-            `Missed Events Playback Feature <https://plugins.jenkins.io/
-            gerrit-trigger/#plugin-content-missed-events-playback-feature
-            -available-from-v-2140>`_.
+            :jenkins-plugins:`Missed Events Playback Feature <gerrit-trigger/#plugin-content-missed-events-playback-feature-available-from-v-2140>`.
 
     :arg str custom-url: Custom URL for a message sent to Gerrit. Build
         details URL will be used if empty. (default '')
@@ -2142,7 +2140,7 @@ def ivy(registry, xml_parent, data):
 
     :arg str path: Path of the ivy file. (optional)
     :arg str settings-path: Ivy Settings Path. (optional)
-    :arg list str properties-file: List of properties file path. Properties
+    :arg list properties-file: List of properties file path. Properties
       will be injected as variables in the ivy settings file. (optional)
     :arg str properties-content: Properties content. Properties will be
       injected as variables in the ivy settings file. (optional)

jenkins_jobs/registry.py

@@ -164,8 +164,7 @@ class ModuleRegistry(object):
 
         :arg str component_type: the name of the component
           (e.g., `builder`)
-        :arg YAMLParser parser: the global YAML Parser
-        :arg Element xml_parent: the parent XML element
+        :arg xml_parent: the parent XML element
         :arg component: component definition
         :arg dict template_data: values that should be interpolated into
           the component definition

jenkins_jobs/sphinx/yaml.py

@@ -23,7 +23,7 @@ import re
 
 from sphinx import addnodes
 from sphinx.domains.python import _pseudo_parse_arglist
-from sphinx.domains.python import PyModulelevel, PyXRefRole
+from sphinx.domains.python import PyFunction, PyXRefRole
 from sphinx.ext.autodoc import Documenter
 from sphinx.ext.autodoc import FunctionDocumenter
 from sphinx.locale import _
@@ -32,7 +32,7 @@ from sphinx.locale import _
 yaml_sig_re = re.compile(r"yaml:\s*(.*)")
 
 
-class PyYAMLFunction(PyModulelevel):
+class PyYAMLFunction(PyFunction):
     def handle_signature(self, sig, signode):
         """Transform a Python signature into RST nodes.
 
@@ -104,7 +104,7 @@ class YAMLFunctionDocumenter(FunctionDocumenter):
         return False
 
     def _find_signature(self, encoding=None):
-        docstrings = Documenter.get_doc(self, encoding, 2)
+        docstrings = Documenter.get_doc(self)
         if len(docstrings) != 1:
             return
         doclines = docstrings[0]
@@ -128,7 +128,7 @@ class YAMLFunctionDocumenter(FunctionDocumenter):
         lines = getattr(self, "__new_doclines", None)
         if lines is not None:
             return [lines]
-        return Documenter.get_doc(self, encoding, ignore)
+        return Documenter.get_doc(self)
 
     def format_signature(self):
         result = self._find_signature()

test-requirements.txt

@@ -5,7 +5,7 @@
 coverage>=4.0 # Apache-2.0
 fixtures>=3.0.0 # Apache-2.0/BSD
 python-subunit>=0.0.18 # Apache-2.0/BSD
-sphinx>=1.5.0,<1.7.0
+sphinx>=4.4.0
 testscenarios>=0.4 # Apache-2.0/BSD
 testtools>=1.4.0 # MIT
 stestr>=2.0.0,!=3.0.0 # Apache-2.0/BSD