X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fjjb%2Flf-rtdv3-jobs.rst;h=85a1480e580919ca69992333dfe79a202591fd5d;hb=refs%2Ftags%2Fv0.49.0;hp=b272bc1db63242c49ebadecb5b34cb98aa024890;hpb=ff490ac1ed8f71b44834dbb025a6f44f4611db39;p=releng%2Fglobal-jjb.git diff --git a/docs/jjb/lf-rtdv3-jobs.rst b/docs/jjb/lf-rtdv3-jobs.rst index b272bc1d..85a1480e 100644 --- a/docs/jjb/lf-rtdv3-jobs.rst +++ b/docs/jjb/lf-rtdv3-jobs.rst @@ -4,36 +4,107 @@ ReadTheDocs Version:3 Jobs ########################## -User setup: +ReadTheDocs V3 jobs support documentation that is structured as a +master documentation project plus a sub-project for each software +component. The master project files are usually maintained in a +"docs" git repository and should contain an index with links to all +the sub-projects. Each sub-project must maintain its documentation +files in a "docs" subdirectory within that software component's git +repository. + +The RTDv3 Jenkins jobs publish documentation by triggering builds at +ReadTheDocs.io. That build process clones the appropriate repository +and transforms Real Simple Text (RST) and other files into HTML. +Master project builds are performed separately from sub-project +builds. + +The ReadTheDocs site supports multiple versions of documentation for +the master project and every sub-project. Every project should have a +development branch that's published at ReadTheDocs under the title +"latest"; in git this is usually the "master" branch. Most projects +also declare releases periodically. ReadTheDocs automatically detects +the creation of git branches and git tags, and publishes the most +recent one under the title "stable." For more details please see +`ReadTheDocs Versions +`_. Teams can +control this process using Jenkins job configuration parameters as +discussed below. + +User setup +---------- + +To transform your rst documentation into a read the docs page, this job must be +configured and created as described in Admin setup below. Once this is complete +the following files must be added to your repository: -To transform your rst documentation into a read the docs page, this job must be configured and -created as described in Admin setup below. Once this is complete the following files must be -added to your repository: +.. code-block:: bash + + .readthedocs.yaml + tox.ini + docs + docs/_static + docs/_static/logo.png + docs/conf.yaml + docs/favicon.ico + docs/index.rst + docs/requirements-docs.txt + docs/conf.py + +Rather than have you copy and paste these files from a set of docs here, the +following repo contains a script that will do this for you. Please refer to the +explanation presented in: https://github.com/lfit-sandbox/test. This is all +currently a beta feature, so feedback is encouraged. The script +`docs_script.sh` is not needed, you can copy the files by hand if you prefer. + +The default location of the tox.ini file is in the git repository root +directory. Optionally your documentation lead may decide to store all tox files +within the required "docs" subdirectory by setting configuration option +"tox-dir" to value "docs/" as discussed below. + +If your project's tox dir is "docs/" and not "." the tox.ini must be +reconfigured with the correct relative paths. + +Once these files are correctly configured in your repository you can test +locally: + +.. code-block:: bash + + tox -e docs,docs-linkcheck + + +Stable Branch Instructions +-------------------------- + +If your project does not create branches, you can skip this step. +Once you branch your project modify your conf.yaml and add the following line: + +.. code-block:: bash + + version: 'ReleaseBranchName' + +This will update the docs and change "master" on the top bar to your branch +name. This change should be done against your release branch, this change will +trigger a Read The Docs build which will create a new landing point for your +documentation. + +This landing point is called /stable/ and is selectable as a version in the +bottom right corner of all Read The Docs pages. Once all projects have +branched and modified their conf.py they will have available their /stable/ +documentation. The process to release the documentation (that is to change the +default landing point of your docs from /latest/ to /stable/) is to change the +default-version in the jenkins job config as follows: + +From: .. code-block:: bash - .readthedocs.yaml - tox.ini - docs - docs/_static - docs/_static/logo.png - docs/conf.yaml - docs/favicon.ico - docs/index.rst - docs/requirements-docs.txt - docs/conf.py - -Rather than have you copy and paste these files from a set of docs here, the following repo -contains a script that will do this for you. Please refer to the explanation presented in: -https://github.com/lfit-sandbox/test -This is all currently a beta feature, so feedback is encouraged. -the script `docs_script.sh` is not needed, you can copy the files by hand if you prefer - -Once these files are correctly configured in your repository you can test locally: + default-version: latest + +To: .. code-block:: bash - tox -e docs,docs-linkcheck + default-version: ReleaseBranchName Admin setup: @@ -52,10 +123,13 @@ Normally this project is called doc or docs or documentation and all other docs be set as a subproject of this job. examples: -global-vars-sandbox.sh: -MASTER_RTD_PROJECT=doc-test -global-vars-production.sh: -MASTER_RTD_PROJECT=doc + +.. code-block:: bash + + global-vars-sandbox.sh: + MASTER_RTD_PROJECT=doc-test + global-vars-production.sh: + MASTER_RTD_PROJECT=doc In this way sandbox jobs will create docs with a test suffix and will not stomp on production documentation. @@ -66,43 +140,48 @@ example file: ci-management/jjb/rtd/rtd.yaml .. code-block:: bash - --- - - project: - name: rtdv3-global-verify - build-node: centos7-builder-1c-1g - jobs: - - rtdv3-global-verify - stream: - - master: - branch: master - - foo: - branch: stable/{stream} - - - project: - name: rtdv3-global-merge - build-node: centos7-builder-1c-1g - jobs: - - rtdv3-global-merge - stream: - - master: - branch: master - - foo: - branch: stable/{stream} + --- + - project: + name: rtdv3-global-verify + build-node: centos7-builder-1c-1g + default-version: latest + tox-dir: "." + jobs: + - rtdv3-global-verify + stream: + - master: + branch: master + - foo: + branch: stable/{stream} + + - project: + name: rtdv3-global-merge + default-version: latest + build-node: centos7-builder-1c-1g + jobs: + - rtdv3-global-merge + stream: + - master: + branch: master + - foo: + branch: stable/{stream} Or add both jobs via a job group: .. code-block:: bash - --- - - project: - name: rtdv3-global - build-node: centos7-builder-1c-1g - jobs: - - rtdv3-global - stream: - - master: - branch: master + --- + - project: + name: rtdv3-global + default-version: latest + tox-dir: "." + build-node: centos7-builder-1c-1g + jobs: + - rtdv3-global + stream: + - master: + branch: master Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven. @@ -111,13 +190,14 @@ Job requires an lftools config section, this is to provide api access to read th .. code-block:: bash - [rtd] - endpoint = https://readthedocs.org/api/v3/ - token = [hidden] + [rtd] + endpoint = https://readthedocs.org/api/v3/ + token = [hidden] Merge Job will create a project on read the docs if none exist. Merge Job will assign a project as a subproject of the master project. Merge job will trigger a build to update docs. +Merge job will change the default version if needed. Macros ====== @@ -153,9 +233,10 @@ Merge job which triggers a build of the docs to readthedocs. :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 minutes before aborting build. (default: 15) - :project-pattern: Project to trigger build against. (default: \*\*) - :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) + :default-version: default page to redirect to for documentation (default /latest/) :disable-job: Whether to disable the job (default: false) + :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) + :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. @@ -208,7 +289,7 @@ Also outputs some info on the build. (default: 10) :submodule-disable: Disable submodule checkout operation. (default: false) - + :tox-dir: Directory containing the project's read the docs tox.ini :gerrit_verify_triggers: Override Gerrit Triggers. :gerrit_trigger_file_paths: Override file paths filter which checks which file modifications will trigger a build.