X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fjjb%2Flf-rtd-jobs.rst;h=393d091719433ddabd7f6155e67a27424fcb05e0;hb=5f28702c4a74e49627390ffd108c1beea141a27b;hp=2b3500ea575be212ae7aa056f2ca9efe7554a91f;hpb=7481ff9faf394dc6c023b2f0d7a635f24fdbb499;p=releng%2Fglobal-jjb.git diff --git a/docs/jjb/lf-rtd-jobs.rst b/docs/jjb/lf-rtd-jobs.rst index 2b3500ea..393d0917 100644 --- a/docs/jjb/lf-rtd-jobs.rst +++ b/docs/jjb/lf-rtd-jobs.rst @@ -7,25 +7,12 @@ ReadTheDocs Jobs Job Groups ========== -{project-name}-rtd-jobs ------------------------ +.. include:: ../job-groups.rst -Jobs to deploy for a project producing ReadTheDocs using Gerrit. +Below is a list of Maven job groups: -:Includes: - - - gerrit-rtd-merge - - gerrit-rtd-verify - -{project-name}-github-rtd-jobs ------------------------------- - -Jobs to deploy for a project producing ReadTheDocs using GitHub. - -:Includes: - - - github-rtd-merge - - github-rtd-verify +.. literalinclude:: ../../jjb/lf-rtd-job-groups.yaml + :language: yaml Macros @@ -44,47 +31,59 @@ Job Templates ReadTheDocs Merge ----------------- -Merge job which triggers a POST of the docs project to readthedocs. There is some setup -required on read the docs to get started with this. After you have created the -individual read the docs project (lets call it "PROJECT" here), then browse to -https://readthedocs.org/dashboard/PROJECT/integrations/ and click on -"Generic API incoming webhook". Here you will see a custom url to trigger the job as -well as a token. Persist the token in the project Jenkins global-settings -file. You will need to put it in a username/password credentials type to make -it available in the global-settings file. set ```rtd-build-url to the -custom build url as defined in read the docs. Also set the rtd-server-id -to the id you specified in the global-settings file, this will enable the script to parse -the token out. Set ```rtd-project``` to your read the docs project name. +Merge job which triggers a POST of the docs project to readthedocs. +To use this job first configure the ``Generic API incoming webhook`` in +ReadTheDocs. To do that follow these steps: + +#. Browse to https://readthedocs.org/dashboard/PROJECT/integrations/ +#. Click on ``Generic API incoming webhook`` + + .. note:: + + If not available click on ``Add integration`` and add the + ``Generic API incoming webhook``. + +#. Copy the custom webhook URL, this is your ``rtd-build-url`` + + For example: https://readthedocs.org/api/v2/webhook/opendaylight/32321/ + +#. Copy the token, this is your ``rtd-token`` :Template Names: - {project-name}-rtd-merge-{stream} - gerrit-rtd-merge - github-rtd-merge +:Comment Trigger: remerge + :Required parameters: :build-node: The node to run build on. :jenkins-ssh-credential: Credential to use for SSH. (Generally set in defaults.yaml) - :rtd-project: This is the name of the project on ReadTheDocs.org. - :rtd-build-url: This is the generic webhook url from readthedocs.org - :global-settings-file: This is the location of the Jenkins global settings file. - This file contains the entry with the location for the readthedocs build token. - :rtd-server-id: This is the id of the entry in the global-settings-file. - + :rtd-build-url: This is the generic webhook url from readthedocs.org. Refer + to the above instructions to generate one. + (Check Admin > Integrations > Generic API incoming webhook) + :rtd-token: The unique token for the project Generic webhook. Refer + to the above instructions to generate one. + (Check Admin > Integrations > Generic API incoming webhook) :Optional parameters: :branch: Git branch to fetch for the build. (default: master) :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7) - :build-timeout: Timeout in seconds before aborting build. (default: 15) + :build-timeout: Timeout in minutes before aborting build. (default: 15) :git-url: base URL of git project. (default: https://github.com) :project-pattern: Project to trigger build against. (default: \*\*) :stream: Keyword representing a release code-name. Often the same as the branch. (default: master) :submodule-recursive: Whether to checkout submodules recursively. (default: true) + :submodule-timeout: Timeout (in minutes) for checkout operation. + (default: 10) + :submodule-disable: Disable submodule checkout operation. + (default: false) :gerrit_merge_triggers: Override Gerrit Triggers. :gerrit_trigger_file_paths: Override file paths filter which checks which @@ -100,13 +99,15 @@ the token out. Set ```rtd-project``` to your read the docs project name. ReadTheDocs Verify ------------------ -Verify job which runs a tox build of the docs project +Verify job which runs tox to test the docs project :Template Names: - {project-name}-rtd-verify-{stream} - gerrit-rtd-verify - github-rtd-verify +:Comment Trigger: recheck|reverify + :Required Parameters: :build-node: The node to run build on. @@ -118,15 +119,21 @@ Verify job which runs a tox build of the docs project :branch: Git branch to fetch for the build. (default: master) :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7) :build-node: The node to run build on. - :build-timeout: Timeout in seconds before aborting build. (default: 15) + :build-timeout: Timeout in minutes before aborting build. (default: 15) :doc-dir: Directory where tox will place built docs. as defined in the tox.ini (default: docs/_build/html) + :gerrit-skip-vote: Skip voting for this job. (default: false) :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) :project-pattern: Project to trigger build against. (default: \*\*) + :python-version: Python version (default: python2) :stream: Keyword representing a release code-name. Often the same as the branch. (default: master) :submodule-recursive: Whether to checkout submodules recursively. (default: true) + :submodule-timeout: Timeout (in minutes) for checkout operation. + (default: 10) + :submodule-disable: Disable submodule checkout operation. + (default: false) :gerrit_verify_triggers: Override Gerrit Triggers. :gerrit_trigger_file_paths: Override file paths filter which checks which