Merge "Ignore py:obj warnings and fail on warnings"

doc/source/conf.py

@@ -283,3 +283,17 @@ linkcheck_ignore = [
     "https://gitorious.org",
 ]
 linkcheck_timeout = 300
+
+nitpicky = True
+nitpick_ignore = [
+    ("py:class", "jenkins_jobs.modules.project_multijob.MultiJob"),
+    ("py:func", "jenkins_jobs.modules.builders.multijob"),
+    ("py:obj", "bool"),
+    ("py:obj", "dict"),
+    ("py:obj", "float"),
+    ("py:obj", "int"),
+    ("py:obj", "list"),
+    ("py:obj", "str"),
+    ("py:obj", "Element"),
+    ("py:obj", "YAMLParser"),
+]

jenkins_jobs/modules/base.py

@@ -57,7 +57,7 @@ class Base(object):
             loaded from JJB Yaml files without variables interpolation or other
             yaml expansions.
 
-        :rtype: boolean
+        :rtype: bool
         """
 
         return False

jenkins_jobs/modules/builders.py

@@ -158,18 +158,18 @@ def copyartifact(registry, xml_parent, data):
         last-successful is specified as which-build
     :arg bool fallback-to-last-successful: specifies to fallback to
         last successful build when upstream-build is specified as which-build
-    :arg string param: specifies to use a build parameter to get the build when
+    :arg str param: specifies to use a build parameter to get the build when
         build-param is specified as which-build
     :arg str upstream-project-name: specifies the project name of downstream
         when downstream-build is specified as which-build
     :arg str upstream-build-number: specifies the number of the build to
         find its downstream build when downstream-build is specified as
         which-build
-    :arg string parameter-filters: Filter matching jobs based on these
+    :arg str parameter-filters: Filter matching jobs based on these
         parameters (optional)
-    :arg string exclude: Specify paths or patterns of artifacts to
+    :arg str exclude: Specify paths or patterns of artifacts to
         exclude, even if specified in "Artifacts to copy". (default '')
-    :arg string result-var-suffix: The build number of the selected build
+    :arg str result-var-suffix: The build number of the selected build
         will be recorded into the variable named
         COPYARTIFACT_BUILD_NUMBER_(SUFFIX)
         for later build steps to reference. (default '')
@@ -3443,7 +3443,7 @@ def cloudformation(registry, xml_parent, data):
     :arg str secret-key: The Amazon API Secret Key (required)
     :arg int sleep: Number of seconds to wait before continuing to the
         next step (default 0)
-    :arg array region: The region to run cloudformation in (required)
+    :arg str region: The region to run cloudformation in (required)
 
         :region values:
             * **us-east-1**

jenkins_jobs/modules/parameters.py

@@ -355,7 +355,7 @@ def credentials_param(registry, xml_parent, data):
 
     :arg bool required: whether this parameter is required (optional, default
         false)
-    :arg string default: default credentials ID (optional)
+    :arg str default: default credentials ID (optional)
     :arg str description: a description of the parameter (optional)
 
     Example:

jenkins_jobs/modules/publishers.py

@@ -288,10 +288,10 @@ def hue_light(registry, xml_parent, data):
 
     :arg int light-id: ID of light. Define multiple lights by a comma as a
         separator (required)
-    :arg string pre-build: Colour of building state (default 'blue')
+    :arg str pre-build: Colour of building state (default 'blue')
-    :arg string good-build: Colour of successful state (default 'green')
+    :arg str good-build: Colour of successful state (default 'green')
-    :arg string unstable-build: Colour of unstable state (default 'yellow')
+    :arg str unstable-build: Colour of unstable state (default 'yellow')
-    :arg string bad-build: Colour of unsuccessful state (default 'red')
+    :arg str bad-build: Colour of unsuccessful state (default 'red')
 
     Full Example:
 
@@ -2888,7 +2888,7 @@ def copy_to_master(registry, xml_parent, data):
 
     :arg list includes: list of file patterns to copy
     :arg list excludes: list of file patterns to exclude
-    :arg string destination: absolute path into which the files will be copied.
+    :arg str destination: absolute path into which the files will be copied.
         If left blank they will be copied into the workspace of the current job
         (default '')
     :arg bool run-after-result: If this is checked then copying files back to
@@ -4847,7 +4847,7 @@ def ircbot(registry, xml_parent, data):
 
     Requires the Jenkins :jenkins-plugins:`IRC Plugin <ircbot>`.
 
-    :arg string strategy: When to send notifications
+    :arg str strategy: When to send notifications
 
         :strategy values:
             * **all** always (default)
@@ -4866,7 +4866,7 @@ def ircbot(registry, xml_parent, data):
         (default false)
     :arg bool notify-fixers: Whether to send notifications to the users that
         have fixed a broken build (default false)
-    :arg string message-type: Channel Notification Message.
+    :arg str message-type: Channel Notification Message.
 
         :message-type values:
             * **summary-scm** for summary and SCM changes (default)
@@ -4884,7 +4884,7 @@ def ircbot(registry, xml_parent, data):
                   * **password** (`str`) Channel password (optional)
                   * **notify-only** (`bool`) Set to true if you want to
                     disallow bot commands (default false)
-    :arg string matrix-notifier: notify for matrix projects
+    :arg str matrix-notifier: notify for matrix projects
         instant-messaging-plugin injects an additional
         field in the configuration form whenever the
         project is a multi-configuration project
@@ -5424,12 +5424,12 @@ def stash(registry, xml_parent, data):
     Requires the Jenkins :jenkins-plugins:`Bitbucket Server Notifier Plugin
     <stashNotifier>`.
 
-    :arg string url: Base url of Stash Server (default "")
+    :arg str url: Base url of Stash Server (default "")
-    :arg string username: Username of Stash Server (default "")
+    :arg str username: Username of Stash Server (default "")
-    :arg string password: Password of Stash Server (default "")
+    :arg str password: Password of Stash Server (default "")
-    :arg string credentials-id: Credentials of Stash Server (optional)
+    :arg str credentials-id: Credentials of Stash Server (optional)
     :arg bool   ignore-ssl: Ignore unverified SSL certificate (default false)
-    :arg string commit-sha1: Commit SHA1 to notify (default "")
+    :arg str commit-sha1: Commit SHA1 to notify (default "")
     :arg bool   include-build-number: Include build number in key
                 (default false)
 
@@ -6128,9 +6128,9 @@ def scan_build(registry, xml_parent, data):
     :arg bool mark-unstable: Mark build as unstable if the number of bugs
         exceeds a threshold (default false)
     :arg int threshold: Threshold for marking builds as unstable (default 0)
-    :arg string exclude-paths: Comma separated paths to exclude from reports
+    :arg str exclude-paths: Comma separated paths to exclude from reports
         (>=1.5) (default '')
-    :arg string report-folder: Folder where generated reports are located
+    :arg str report-folder: Folder where generated reports are located
         (>=1.7) (default 'clangScanBuildReports')
 
     Full Example:
@@ -6269,10 +6269,10 @@ def downstream_ext(registry, xml_parent, data):
     <downstream-ext>`.
 
     :arg list projects: Projects to build (required)
-    :arg string condition: comparison condition used for the criteria.
+    :arg str condition: comparison condition used for the criteria.
       One of 'equal-or-over', 'equal-or-under', 'equal'
       (default 'equal-or-over')
-    :arg string criteria: Trigger downstream job if build results meets
+    :arg str criteria: Trigger downstream job if build results meets
       condition. One of 'success', 'unstable', 'failure' or
       'aborted' (default 'success')
     :arg bool only-on-scm-change: Trigger only if downstream project
@@ -7857,8 +7857,8 @@ def tasks(registry, xml_parent, data):
     """yaml: tasks
 
     Scans the workspace files for open tasks and generates a trend report.
-    Requires the Jenkins
+
-    :jenkins-plugin:`Task Scanner Plugin <tasks>`.
+    Requires the Jenkins :jenkins-plugins:`Task Scanner Plugin <tasks>`.
 
     :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/triggers.py

@@ -752,7 +752,7 @@ def pollscm(registry, xml_parent, data):
 
     .. _cron:
 
-    :arg string cron: the polling interval (cron syntax, required)
+    :arg str cron: the polling interval (cron syntax, required)
     :arg bool ignore-post-commit-hooks: Ignore changes notified by SCM
         post-commit hooks. The subversion-plugin supports this since
         version 1.44. (default false)
@@ -815,8 +815,8 @@ def pollurl(registry, xml_parent, data):
     Trigger when the HTTP response from a URL changes.
     Requires the Jenkins :jenkins-plugins:`URLTrigger Plugin <urltrigger>`.
 
-    :arg string cron: cron syntax of when to run (default '')
+    :arg str cron: cron syntax of when to run (default '')
-    :arg string polling-node: Restrict where the polling should run.
+    :arg str polling-node: Restrict where the polling should run.
                               (optional)
     :arg list urls: List of URLs to monitor
 
@@ -824,9 +824,9 @@ def pollurl(registry, xml_parent, data):
             * **proxy** (`bool`) -- Activate the Jenkins proxy (default false)
             * **timeout** (`int`) -- Connect/read timeout in seconds
               (default 300)
-            * **username** (`string`) -- User name for basic authentication
+            * **username** (`str`) -- User name for basic authentication
               (optional)
-            * **password** (`string`) -- Password for basic authentication
+            * **password** (`str`) -- Password for basic authentication
               (optional)
             * **check-status** (`int`) -- Check for a specific HTTP status
               code (optional)
@@ -1051,16 +1051,16 @@ def github_pull_request(registry, xml_parent, data):
     :arg list org-list: orgs whose users should be white listed (optional)
     :arg bool allow-whitelist-orgs-as-admins: members of white listed orgs
         will have admin rights. (default false)
-    :arg string cron: cron syntax of when to run (optional)
+    :arg str cron: cron syntax of when to run (optional)
-    :arg string trigger-phrase: when filled, commenting this phrase
+    :arg str trigger-phrase: when filled, commenting this phrase
         in the pull request will trigger a build (optional)
     :arg bool only-trigger-phrase: only commenting the trigger phrase
         in the pull request will trigger a build (default false)
-    :arg string skip-build-phrase: when filled, adding this phrase to
+    :arg str skip-build-phrase: when filled, adding this phrase to
         the pull request title or body will not trigger a build (optional)
-    :arg string black-list-labels: list of GitHub labels for which the build
+    :arg str black-list-labels: list of GitHub labels for which the build
         should not be triggered (optional)
-    :arg string white-list-labels: list of GitHub labels for which the build
+    :arg str white-list-labels: list of GitHub labels for which the build
         should only be triggered. (Leave blank for 'any') (optional)
     :arg bool github-hooks: use github hook (default false)
     :arg bool permit-all: build every pull request automatically
@@ -1075,29 +1075,29 @@ def github_pull_request(registry, xml_parent, data):
         allows you to selectively prevent pull requests builds destined for
         these branches. Supports regular expressions (e.g. 'master',
         'feature-.*'). (optional)
-    :arg string auth-id: the auth id to use (optional)
+    :arg str auth-id: the auth id to use (optional)
-    :arg string build-desc-template: the template for build descriptions in
+    :arg str build-desc-template: the template for build descriptions in
         jenkins (optional)
-    :arg string status-context: the context to include on PR status comments
+    :arg str status-context: the context to include on PR status comments
         (optional)
-    :arg string triggered-status: the status message to set when the build has
+    :arg str triggered-status: the status message to set when the build has
         been triggered (optional)
-    :arg string started-status: the status comment to set when the build has
+    :arg str started-status: the status comment to set when the build has
         been started (optional)
-    :arg string status-url: the status URL to set (optional)
+    :arg str status-url: the status URL to set (optional)
     :arg bool status-add-test-results: add test result one-liner to status
         message (optional)
-    :arg string success-status: the status message to set if the job succeeds
+    :arg str success-status: the status message to set if the job succeeds
         (optional)
-    :arg string failure-status: the status message to set if the job fails
+    :arg str failure-status: the status message to set if the job fails
         (optional)
-    :arg string error-status: the status message to set if the job errors
+    :arg str error-status: the status message to set if the job errors
         (optional)
-    :arg string success-comment: comment to add to the PR on a successful job
+    :arg str success-comment: comment to add to the PR on a successful job
         (optional)
-    :arg string failure-comment: comment to add to the PR on a failed job
+    :arg str failure-comment: comment to add to the PR on a failed job
         (optional)
-    :arg string error-comment: comment to add to the PR on an errored job
+    :arg str error-comment: comment to add to the PR on an errored job
         (optional)
     :arg bool cancel-builds-on-update: cancel existing builds when a PR is
         updated (optional)
@@ -1298,27 +1298,27 @@ def gitlab_merge_request(registry, xml_parent, data):
     Requires the Jenkins :jenkins-plugins:`Gitlab MergeRequest Builder Plugin
     <ghprb>`.
 
-    :arg string cron: Cron syntax of when to run (required)
+    :arg str cron: Cron syntax of when to run (required)
-    :arg string project-path: Gitlab-relative path to project (required)
+    :arg str project-path: Gitlab-relative path to project (required)
-    :arg string target-branch-regex: Allow execution of this job for certain
+    :arg str target-branch-regex: Allow execution of this job for certain
         branches only (default ''). Requires Gitlab MergeRequest Builder
         Plugin >= 2.0.0
-    :arg string use-http-url: Use the HTTP(S) URL to fetch/clone repository
+    :arg str use-http-url: Use the HTTP(S) URL to fetch/clone repository
         (default false)
-    :arg string assignee-filter: Only MRs with this assigned user will
+    :arg str assignee-filter: Only MRs with this assigned user will
         trigger the build automatically (default 'jenkins')
-    :arg string tag-filter: Only MRs with this label will trigger the build
+    :arg str tag-filter: Only MRs with this label will trigger the build
         automatically (default 'Build')
-    :arg string trigger-comment: Force build if this comment is the last
+    :arg str trigger-comment: Force build if this comment is the last
         in merge reguest (default '')
-    :arg string publish-build-progress-messages: Publish build progress
+    :arg str publish-build-progress-messages: Publish build progress
         messages (except build failed) (default true)
 
         .. deprecated:: 2.0.0
 
-    :arg string auto-close-failed: On failure, auto close the request
+    :arg str auto-close-failed: On failure, auto close the request
         (default false)
-    :arg string auto-merge-passed: On success, auto merge the request
+    :arg str auto-merge-passed: On success, auto merge the request
         (default false)
 
     Example (version < 2.0.0):
@@ -2324,39 +2324,39 @@ def generic_webhook_trigger(registry, xml_parent, data):
     <generic-webhook-trigger>`.
 
 
-    :arg string token: A token to use to trigger the job. (default '')
+    :arg str token: A token to use to trigger the job. (default '')
     :arg bool print-post-content: Print post content in job log.
     :arg bool print-contrib-var: Print contributed variables in job log.
     :arg bool silent-response: Avoid responding with information about
      triggered jobs.
-    :arg string cause: This will be displayed in any triggered job.
+    :arg str cause: This will be displayed in any triggered job.
-    :arg string regex-filter-expression: Regular expression to test on the
+    :arg str regex-filter-expression: Regular expression to test on the
      evaluated text specified in regex-filter-text
-    :arg string regex-filter-text: Text to test for the given
+    :arg str regex-filter-text: Text to test for the given
      regexp-filter-expression.
 
     :arg list post-content-params: Parameters to use from posted JSON/XML
 
-        :post-content-params: * **type** (`string`) -- JSONPath or XPath
+        :post-content-params: * **type** (`str`) -- JSONPath or XPath
-            * **key** (`string`) -- Variable name
+            * **key** (`str`) -- Variable name
-            * **value** (`string`) -- Expression to evaluate in POST content.
+            * **value** (`str`) -- Expression to evaluate in POST content.
               Use JSONPath for JSON or XPath for XML.
-            * **regex-filter** (`string`) -- Anything in the evaluated value,
+            * **regex-filter** (`str`) -- Anything in the evaluated value,
               matching this regular expression, will be removed. (optional)
-            * **default-value** (`string`) -- This value will be used if
+            * **default-value** (`str`) -- This value will be used if
               expression does not match anything. (optional)
 
     :arg list request-params: Parameters to use passed in as request arguments
 
-        :request-params: * **key** (`string`) -- Name of request parameter
+        :request-params: * **key** (`str`) -- Name of request parameter
-            * **regex-filter** (`string`) -- Anything in the evaluated value,
+            * **regex-filter** (`str`) -- Anything in the evaluated value,
               matching this regular expression, will be removed. (optional)
     :arg list header-params: Parameters to use passed in as headers
 
-        :header-params: * **key** (`string`) -- Name of request header in
+        :header-params: * **key** (`str`) -- Name of request header in
               lowercase. Resulting variable name has '_' instead of '-'
               characters.
-            * **regex-filter** (`string`) -- Anything in the evaluated value,
+            * **regex-filter** (`str`) -- Anything in the evaluated value,
               matching this regular expression, will be removed. (optional)
 
     Example:

jenkins_jobs/modules/wrappers.py

@@ -501,7 +501,7 @@ def ansicolor(registry, xml_parent, data):
 
     Requires the Jenkins :jenkins-plugins:`Ansi Color Plugin <ansicolor>`.
 
-    :arg string colormap: Color mapping to use (default xterm)
+    :arg str colormap: Color mapping to use (default xterm)
 
     Minimal Example:
 
@@ -1537,7 +1537,7 @@ def release(registry, xml_parent, data):
     :arg bool keep-forever: Keep build forever (default true)
     :arg bool override-build-parameters: Enable build-parameter override
         (default false)
-    :arg string version-template: Release version template (default '')
+    :arg str version-template: Release version template (default '')
     :arg list parameters: Release parameters (see the :ref:`Parameters` module)
     :arg list pre-build: Pre-build steps (see the :ref:`Builders` module)
     :arg list post-build: Post-build steps (see :ref:`Builders`)
@@ -1771,7 +1771,7 @@ def pre_scm_buildstep(registry, xml_parent, data):
     Requires the Jenkins :jenkins-plugins:`Pre SCM BuildStep
     <preSCMbuildstep>`.
 
-    :arg string failOnError: Specifies if the job should fail on error
+    :arg str failOnError: Specifies if the job should fail on error
         (plugin >= 0.3) (default false).
     :arg list buildsteps: List of build steps to execute
 

jenkins_jobs/registry.py

@@ -94,7 +94,7 @@ class ModuleRegistry(object):
         This allows module authors to differentiate generated XML output based
         on information such as specific plugin versions.
 
-        :arg string plugin_name: Either the shortName or longName of a plugin
+        :arg str 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``
 
@@ -146,7 +146,7 @@ class ModuleRegistry(object):
         of component, and benefit from extensibility via Python
         entry points and Jenkins Job Builder :ref:`Macros <macro>`.
 
-        :arg string component_type: the name of the component
+        :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

tox.ini

@@ -76,7 +76,7 @@ commands = jenkins-jobs test -o .test/new/out/ .test/new/config/
 [testenv:docs]
 commands =
     {[tox]install_test_deps}
-    sphinx-build -n -b html -d doc/build/doctrees doc/source doc/build/html
+    sphinx-build -n -W -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
@@ -84,7 +84,7 @@ commands =
 # through the proxy environment settings to be able to validate any urls.
 commands =
     {[tox]install_test_deps}
-    sphinx-build -n -b linkcheck -d doc/build/doctrees doc/source doc/build/linkcheck
+    sphinx-build -n -W -b linkcheck -d doc/build/doctrees doc/source doc/build/linkcheck
 
 [testenv:venv]
 commands = {posargs}