Documentation Jobs

opendev-nox-docs

Build documentation with “nox”.

Uses nox with the docs session.

opendev-publish-nox-docs-base

Publish a ref-based documentation build.

Use this in the tag or release pipelines to publish a build based on a newly-created tag.

This is an abstract job intended to be inherited from in an OpenDev tenant and an appropriate secret added.

afs

:type: dict

This is expected to be a Zuul Secret with these keys:

:type: dict.keytab

The AFS keytab for the service principal.

:type: dict.service_name

The name of the service princpal.

:type: dict.targets

This is a dict containing information about where docs should be published.

:type: dict.targets.master

This is expected to be a dict with a single key value pair: path: the full docs publication path to use if the job is run on the master branch.

:type: dict.targets.branch

This is expected to be a dict with a key value pair: path: the full docs publication path to use if the job is run on any other branch.

:type: dict.targets.tag

This is expected to be a dict with a key value pair: path: the full docs publication path to use if the job is run on a tag.

opendev-publish-nox-docs

Publish a ref-based documentation build.

Use this in the tag or release pipelines to publish a build based on a newly-created tag.

opendev-publish-unversioned-nox-docs

Publish a ref-based documentation build to “latest” always.

Use this in the tag or release pipelines to publish a build based on a newly-created tag but published as if it were a branch tip build instead. This is useful when the project has only a single branch and multiple version-specific copies of its documentation are undesirable, or when triggered by a tag alongside a version-specific publication job.

opendev-tox-docs

Build documentation with “tox”.

Uses tox with the docs environment.

opendev-publish-tox-docs-base

Publish a ref-based documentation build.

Use this in the tag or release pipelines to publish a build based on a newly-created tag.

This is an abstract job intended to be inherited from in an OpenDev tenant and an appropriate secret added.

afs

:type: dict

This is expected to be a Zuul Secret with these keys:

:type: dict.keytab

The AFS keytab for the service principal.

:type: dict.service_name

The name of the service princpal.

:type: dict.targets

This is a dict containing information about where docs should be published.

:type: dict.targets.master

This is expected to be a dict with a single key value pair: path: the full docs publication path to use if the job is run on the master branch.

:type: dict.targets.branch

This is expected to be a dict with a key value pair: path: the full docs publication path to use if the job is run on any other branch.

:type: dict.targets.tag

This is expected to be a dict with a key value pair: path: the full docs publication path to use if the job is run on a tag.

opendev-publish-tox-docs

Publish a ref-based documentation build.

Use this in the tag or release pipelines to publish a build based on a newly-created tag.

opendev-publish-unversioned-tox-docs

Publish a ref-based documentation build to “latest” always.

Use this in the tag or release pipelines to publish a build based on a newly-created tag but published as if it were a branch tip build instead. This is useful when the project has only a single branch and multiple version-specific copies of its documentation are undesirable, or when triggered by a tag alongside a version-specific publication job.

opendev-promote-docs-base

Publish a previously built branch-tip documentation tarball.

Use this in the promote pipeline to publish a branch tip tarball built in the gate pipeline.

This is an abstract job intended to be inherited from in an OpenDev tenant and an appropriate secret added.

afs

:type: dict

This is expected to be a Zuul Secret with these keys:

:type: dict.keytab

The AFS keytab for the service principal.

:type: dict.service_name

The name of the service princpal.

:type: dict.targets

This is a dict containing information about where docs should be published.

:type: dict.targets.master

This is expected to be a dict with a single key value pair: path: the full docs publication path to use if the job is run on the master branch.

:type: dict.targets.branch

This is expected to be a dict with a key value pair: path: the full docs publication path to use if the job is run on any other branch.

:type: dict.targets.tag

This is expected to be a dict with a key value pair: path: the full docs publication path to use if the job is run on a tag.

:type: dict.docs_redirect_path

If this variable is present, a .htaccess redirect will be created at this path when the job is run on the master branch. For example, it can be used to redirect “project/” to “project/latest”.

:type: dict.docs_redirect_content

The contents of the .htaccess file in docs_redirect_path.

download_artifact_job

The name of the job which built the docs artifact which this job should download and promote.

download_artifact_job.write_root_marker

If this is set to false, then the root marker file is not written.

Warning: setting this parameter incorrectly can result in loss of published data.

opendev-promote-docs

Publish a previously built branch-tip documentation tarball.

Use this in the promote pipeline to publish a branch tip tarball built in the gate pipeline.

The documentation tarball is published to https://docs.opendev.org/{{ zuul.project.name }}.

Publishes depending on branch to latest/ (for master), or the basename of the branch like train (for stable/train).