diff --git a/doc/source/conf.py b/doc/source/conf.py index 0279f786e..238de16ff 100644 --- a/doc/source/conf.py +++ b/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"), +] diff --git a/jenkins_jobs/modules/base.py b/jenkins_jobs/modules/base.py index dca0c7f1e..8dc2be720 100644 --- a/jenkins_jobs/modules/base.py +++ b/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 diff --git a/jenkins_jobs/modules/builders.py b/jenkins_jobs/modules/builders.py index 584c1eefa..71765f852 100644 --- a/jenkins_jobs/modules/builders.py +++ b/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** diff --git a/jenkins_jobs/modules/parameters.py b/jenkins_jobs/modules/parameters.py index a5b25c964..fca02e1c2 100644 --- a/jenkins_jobs/modules/parameters.py +++ b/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: diff --git a/jenkins_jobs/modules/publishers.py b/jenkins_jobs/modules/publishers.py index f2a8ef5bd..9205cde0c 100755 --- a/jenkins_jobs/modules/publishers.py +++ b/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 string good-build: Colour of successful state (default 'green') - :arg string unstable-build: Colour of unstable state (default 'yellow') - :arg string bad-build: Colour of unsuccessful state (default 'red') + :arg str pre-build: Colour of building state (default 'blue') + :arg str good-build: Colour of successful state (default 'green') + :arg str unstable-build: Colour of unstable state (default 'yellow') + :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 `. - :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 `. - :arg string url: Base url of Stash Server (default "") - :arg string username: Username of Stash Server (default "") - :arg string password: Password of Stash Server (default "") - :arg string credentials-id: Credentials of Stash Server (optional) + :arg str url: Base url of Stash Server (default "") + :arg str username: Username of Stash Server (default "") + :arg str password: Password of Stash Server (default "") + :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): `. :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 `. + + Requires the Jenkins :jenkins-plugins:`Task Scanner 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/triggers.py b/jenkins_jobs/modules/triggers.py index b17709c5c..90f9e2eed 100644 --- a/jenkins_jobs/modules/triggers.py +++ b/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 `. - :arg string cron: cron syntax of when to run (default '') - :arg string polling-node: Restrict where the polling should run. + :arg str cron: cron syntax of when to run (default '') + :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 string trigger-phrase: when filled, commenting this phrase + :arg str cron: cron syntax of when to run (optional) + :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 string build-desc-template: the template for build descriptions in + :arg str auth-id: the auth id to use (optional) + :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 `. - :arg string cron: Cron syntax of when to run (required) - :arg string project-path: Gitlab-relative path to project (required) - :arg string target-branch-regex: Allow execution of this job for certain + :arg str cron: Cron syntax of when to run (required) + :arg str project-path: Gitlab-relative path to project (required) + :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): `. - :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 string regex-filter-expression: Regular expression to test on the + :arg str cause: This will be displayed in any triggered job. + :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 - * **key** (`string`) -- Variable name - * **value** (`string`) -- Expression to evaluate in POST content. + :post-content-params: * **type** (`str`) -- JSONPath or XPath + * **key** (`str`) -- Variable name + * **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 - * **regex-filter** (`string`) -- Anything in the evaluated value, + :request-params: * **key** (`str`) -- Name of request parameter + * **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: diff --git a/jenkins_jobs/modules/wrappers.py b/jenkins_jobs/modules/wrappers.py index ac8761d10..77230c8e4 100644 --- a/jenkins_jobs/modules/wrappers.py +++ b/jenkins_jobs/modules/wrappers.py @@ -501,7 +501,7 @@ def ansicolor(registry, xml_parent, data): Requires the Jenkins :jenkins-plugins:`Ansi Color Plugin `. - :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 `. - :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 diff --git a/jenkins_jobs/registry.py b/jenkins_jobs/registry.py index 7ac93d77d..5f1d7f9c1 100644 --- a/jenkins_jobs/registry.py +++ b/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:///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 `. - :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 diff --git a/tox.ini b/tox.ini index e8a78569b..aa93b6906 100644 --- a/tox.ini +++ b/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}