Merge branch 'ci-only-docs' into 'develop'

  PYTHONUNBUFFERED: "1"

  FF_USE_WINDOWS_JOB_OBJECT: 1

.only-docs:

  rules:

    # Docs-only opt out of the full CI: the only heavy job that starts

    # automatically is linux:test-source (one job per Python version);

    # everything else is manual already. Skip it when the merge request carries

    # the "Only docs" label, or when its title or the tip commit message carries

    # the case-sensitive marker [ONLY DOCS] (the marker also works on the branch

    # pipeline of a branch with no merge request). Skipped jobs are manual, not

    # never, so they can still be started from the pipeline view. The default

    # branch, the maintenance branches and tags are never affected.

    - if: >-

        $CI_COMMIT_TAG == null && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH &&

        $CI_COMMIT_BRANCH !~ /^maintenance\/.*/ &&

        ($CI_COMMIT_MESSAGE =~ /\[ONLY DOCS\]/ ||

        $CI_MERGE_REQUEST_TITLE =~ /\[ONLY DOCS\]/ ||

        $CI_MERGE_REQUEST_LABELS =~ /Only docs/)

      when: manual

      allow_failure: true

.rules-wheel:

  rules:

    - if: '$CI_PIPELINE_SOURCE == "schedule"'

linux:test-source:

  stage: test

  rules:

    - !reference [.only-docs, rules]

    - when: on_success

  image: registry.gitlab.com/tango-controls/docker/micromamba:2.5.0

  tags:

    - linux

- CI runs a merge request pipeline as soon as an MR is open, and a branch pipeline for a

  branch without an MR, never both for the same commit.  Pushing to the MR cancels the

  pipeline of the previous push.

- For a documentation-only MR the test suite is a waste of resources.  Add the `Only docs`

  label to the MR (or the case-sensitive marker `[ONLY DOCS]` in the MR title, or in the

  message of the commit you push), and the `linux:test-source` jobs become manual, so only

  linting, the sdist build and the documentation build run.  Every other job is manual anyway,

  and any of them can still be started from the pipeline view.

## MyST and Sphinx