.docs-base:
  variables:
    BUILDER: html
  extends:
    - .fdo.ci-fairy
  artifacts:
    expose_as: 'Documentation preview'
    paths:
    - public/
  script:
  - apk --no-cache add coreutils graphviz py3-clang clang-dev musl-dev linux-headers
  - pip3 install sphinx===5.1.1 mako===1.2.3 hawkmoth===0.16.0
  - sphinx-build -W -b $BUILDER docs public

pages:
  extends: .docs-base
  stage: deploy
  needs: []
  rules:
    - !reference [.no_scheduled_pipelines-rules, rules]
    - if: '$CI_PROJECT_NAMESPACE == "mesa" && $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH && $CI_COMMIT_BRANCH'
      changes: &docs-or-ci
      - docs/**/*
      - .gitlab-ci.yml
      # All the source files documentation is extracted from
      # git grep -h ":file: src/" -- docs | sort | uniq
      - src/compiler/nir/nir.h
      - src/intel/isl/**/*
      - src/vulkan/runtime/**/*
      when: always
    # Other cases default to never

test-docs:
  extends: .docs-base
  # Cancel job if a newer commit is pushed to the same branch
  interruptible: true
  stage: deploy
  needs: []
  rules:
    - !reference [.no_scheduled_pipelines-rules, rules]
    - if: '$CI_COMMIT_BRANCH && $CI_PROJECT_NAMESPACE != "mesa"'
      changes: *docs-or-ci
      when: manual
    # Other cases default to never

test-docs-mr:
  extends:
    - test-docs
  needs:
    - job: sanity
      optional: true
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes: *docs-or-ci
      when: on_success
    # Other cases default to never

linkcheck-docs:
  extends: .docs-base
  # Cancel job if a newer commit is pushed to the same branch
  interruptible: true
  stage: deploy
  needs: []
  rules:
    - !reference [.scheduled_pipeline-rules, rules]
  allow_failure: true
  variables:
    BUILDER: linkcheck