From 930dd24dd2bab49170e5d847833a01070c721d61 Mon Sep 17 00:00:00 2001 From: Eric Ball Date: Thu, 24 Mar 2022 18:21:03 -0700 Subject: [PATCH] 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 Change-Id: Iba65fb724f098f3e4a0b20f2a183cb2ea3c450ea --- .zuul.yaml | 4 +--- doc/source/extending.rst | 5 ++--- jenkins_jobs/modules/base.py | 3 +-- jenkins_jobs/modules/builders.py | 2 +- jenkins_jobs/modules/publishers.py | 14 +++++++------- jenkins_jobs/modules/reporters.py | 2 +- jenkins_jobs/modules/scm.py | 2 +- jenkins_jobs/modules/triggers.py | 6 ++---- jenkins_jobs/registry.py | 3 +-- jenkins_jobs/sphinx/yaml.py | 8 ++++---- test-requirements.txt | 2 +- 11 files changed, 22 insertions(+), 29 deletions(-) diff --git a/.zuul.yaml b/.zuul.yaml index 5d4c90c18..c95e4d691 100644 --- a/.zuul.yaml +++ b/.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 diff --git a/doc/source/extending.rst b/doc/source/extending.rst index c2def6b6f..913d2c3c1 100644 --- a/doc/source/extending.rst +++ b/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 diff --git a/jenkins_jobs/modules/base.py b/jenkins_jobs/modules/base.py index 8dc2be720..8d505fda4 100644 --- a/jenkins_jobs/modules/base.py +++ b/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 """ diff --git a/jenkins_jobs/modules/builders.py b/jenkins_jobs/modules/builders.py index cfc6d06d7..b84c620eb 100644 --- a/jenkins_jobs/modules/builders.py +++ b/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: diff --git a/jenkins_jobs/modules/publishers.py b/jenkins_jobs/modules/publishers.py index f6f52f58a..c3df0620e 100755 --- a/jenkins_jobs/modules/publishers.py +++ b/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 diff --git a/jenkins_jobs/modules/reporters.py b/jenkins_jobs/modules/reporters.py index 010afb046..e92cc25ca 100644 --- a/jenkins_jobs/modules/reporters.py +++ b/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. diff --git a/jenkins_jobs/modules/scm.py b/jenkins_jobs/modules/scm.py index 391f5b475..d5681e718 100644 --- a/jenkins_jobs/modules/scm.py +++ b/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 diff --git a/jenkins_jobs/modules/triggers.py b/jenkins_jobs/modules/triggers.py index f7f5ab09d..4afbb2241 100644 --- a/jenkins_jobs/modules/triggers.py +++ b/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 `_. + :jenkins-plugins:`Missed Events Playback Feature `. :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) diff --git a/jenkins_jobs/registry.py b/jenkins_jobs/registry.py index 4ca9a83a9..9418dea52 100644 --- a/jenkins_jobs/registry.py +++ b/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 diff --git a/jenkins_jobs/sphinx/yaml.py b/jenkins_jobs/sphinx/yaml.py index b63262a91..f22714a4c 100644 --- a/jenkins_jobs/sphinx/yaml.py +++ b/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() diff --git a/test-requirements.txt b/test-requirements.txt index db1d8077d..2d38d0385 100644 --- a/test-requirements.txt +++ b/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