esp-idf/.gitlab/ci/docs.yml

.patterns-docs-full: &patterns-docs-full
  - ".gitlab/ci/docs.yml"
  - "docs/**/*"
  - "**/*.rst"
  - "CONTRIBUTING.rst"
  - "**/soc_caps.h"

.patterns-docs-partial: &patterns-docs-partial
  - "components/**/*.h"
  - "components/**/Kconfig*"
  - "components/**/CMakeList.txt"
  - "components/**/sdkconfig*"
  - "tools/tools.json"
  - "tools/idf_tools.py"

.patterns-example-readme: &patterns-example-readme
  - "examples/**/*.md"

.patterns-docs-preview: &patterns-docs-preview
  - "docs/**/*"

.if-protected: &if-protected
  if: '($CI_COMMIT_REF_NAME == "master" || $CI_COMMIT_BRANCH =~ /^release\/v/ || $CI_COMMIT_TAG =~ /^v\d+\.\d+(\.\d+)?($|-)/)'

.if-protected-no_label: &if-protected-no_label
  if: '($CI_COMMIT_REF_NAME == "master" || $CI_COMMIT_BRANCH =~ /^release\/v/ || $CI_COMMIT_TAG =~ /^v\d+\.\d+(\.\d+)?($|-)/) && $BOT_TRIGGER_WITH_LABEL == null'

.if-qa-test-tag: &if-qa-test-tag
  if: '$CI_COMMIT_TAG =~ /^qa-test/'

.if-label-build_docs: &if-label-build_docs
  if: '$BOT_LABEL_BUILD_DOCS || $CI_MERGE_REQUEST_LABELS =~ /^(?:[^,\n\r]+,)*build_docs(?:,[^,\n\r]+)*$/i'

.if-label-docs_full: &if-label-docs_full
  if: '$BOT_LABEL_DOCS_FULL || $CI_MERGE_REQUEST_LABELS =~ /^(?:[^,\n\r]+,)*docs_full(?:,[^,\n\r]+)*$/i'

.if-dev-push: &if-dev-push
  if: '$CI_COMMIT_REF_NAME != "master" && $CI_COMMIT_BRANCH !~ /^release\/v/ && $CI_COMMIT_TAG !~ /^v\d+\.\d+(\.\d+)?($|-)/ && $CI_COMMIT_TAG !~ /^qa-test/ && ($CI_PIPELINE_SOURCE == "push" || $CI_PIPELINE_SOURCE == "merge_request_event")'

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

.doc-rules:build:docs-full:
  rules:
    - <<: *if-qa-test-tag
      when: never
    - <<: *if-schedule
    - <<: *if-label-build_docs
    - <<: *if-label-docs_full
    - <<: *if-dev-push
      changes: *patterns-docs-full

.doc-rules:build:docs-full-prod:
  rules:
    - <<: *if-qa-test-tag
      when: never
    - <<: *if-protected-no_label

.doc-rules:build:docs-partial:
  rules:
    - <<: *if-qa-test-tag
      when: never
    - <<: *if-dev-push
      changes: *patterns-docs-full
      when: never
    - <<: *if-dev-push
      changes: *patterns-docs-partial

# stage: pre_check
check_readme_links:
  extends:
    - .pre_check_template
  tags: ["build", "amd64", "internet"]
  allow_failure: true
  rules:
    - <<: *if-protected
    - <<: *if-dev-push
      changes: *patterns-example-readme
  script:
    - python ${IDF_PATH}/tools/ci/check_readme_links.py

check_docs_lang_sync:
  extends:
    - .pre_check_template
    - .doc-rules:build:docs-full
  script:
    - cd docs
    - ./check_lang_folder_sync.sh

.build_docs_template:
  image: $ESP_IDF_DOC_ENV_IMAGE
  stage: build_doc
  tags:
    - build_docs
  script:
    - if [ -n "${BREATHE_ALT_INSTALL_URL}" ]; then pip uninstall -y breathe && pip install -U ${BREATHE_ALT_INSTALL_URL}; fi
    - cd docs
    - build-docs -t $DOCTGT -bs $DOC_BUILDERS -l $DOCLANG build
  parallel:
    matrix:
      - DOCLANG: ["en", "zh_CN"]
        DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32h2", "esp32p4"]

check_docs_gh_links:
  image: $ESP_IDF_DOC_ENV_IMAGE
  extends:
    - .pre_check_template
    - .doc-rules:build:docs-full
  script:
    - cd docs
    - build-docs gh-linkcheck

# Doc jobs have a lot of special cases, we specify rules here directly instead
# in dependencies.yml to simplify things
build_docs_html_full:
  extends:
    - .build_docs_template
    - .doc-rules:build:docs-full
  needs:
    - job: fast_template_app
      artifacts: false
      optional: true
  artifacts:
    when: always
    paths:
      - docs/_build/*/*/*.txt
      - docs/_build/*/*/html/*
    expire_in: 4 days
  variables:
    DOC_BUILDERS: "html"

build_docs_html_full_prod:
  extends:
    - .build_docs_template
    - .doc-rules:build:docs-full-prod
  dependencies: [] # Stop build_docs jobs from downloading all previous job's artifacts
  artifacts:
    when: always
    paths:
      - docs/_build/*/*/*.txt
      - docs/_build/*/*/html/*
    expire_in: 4 days
  variables:
    DOC_BUILDERS: "html"

build_docs_html_partial:
  extends:
    - .build_docs_template
    - .doc-rules:build:docs-partial
  needs:
    - job: fast_template_app
      artifacts: false
      optional: true
  artifacts:
    when: always
    paths:
      - docs/_build/*/*/*.txt
      - docs/_build/*/*/html/*
    expire_in: 4 days
  variables:
    DOC_BUILDERS: "html"
  parallel:
    matrix:
      - DOCLANG: "en"
        DOCTGT: "esp32"
      - DOCLANG: "zh_CN"
        DOCTGT: "esp32p4"

build_docs_pdf:
  extends:
    - .build_docs_template
    - .doc-rules:build:docs-full
  needs:
    - job: fast_template_app
      artifacts: false
      optional: true
  artifacts:
    when: always
    paths:
      - docs/_build/*/*/latex/*
    expire_in: 4 days
  variables:
    DOC_BUILDERS: "latex"

build_docs_pdf_prod:
  extends:
    - .build_docs_template
    - .doc-rules:build:docs-full-prod
  dependencies: [] # Stop build_docs jobs from downloading all previous job's artifacts
  artifacts:
    when: always
    paths:
      - docs/_build/*/*/latex/*
    expire_in: 4 days
  variables:
    DOC_BUILDERS: "latex"

.deploy_docs_template:
  image: $ESP_IDF_DOC_ENV_IMAGE
  variables:
    DOCS_BUILD_DIR: "${IDF_PATH}/docs/_build/"
    PYTHONUNBUFFERED: 1
  stage: test_deploy
  tags:
    - deploy
    - shiny
  script:
    - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
    - export GIT_VER=$(git describe --always ${PIPELINE_COMMIT_SHA} --)
    - deploy-docs

# stage: test_deploy
deploy_docs_preview:
  extends:
    - .deploy_docs_template
  rules:
    - <<: *if-label-build_docs
    - <<: *if-label-docs_full
    - <<: *if-dev-push
      changes: *patterns-docs-preview
  needs:
    - job: build_docs_html_partial
      optional: true
    - job: build_docs_html_full
      optional: true
    - job: build_docs_pdf
      optional: true
  variables:
    TYPE: "preview"
    # older branches use DOCS_DEPLOY_KEY, DOCS_SERVER, DOCS_SERVER_USER, DOCS_PATH for preview server so we keep these names for 'preview'
    DOCS_DEPLOY_PRIVATEKEY: "$DOCS_DEPLOY_KEY"
    DOCS_DEPLOY_SERVER: "$DOCS_SERVER"
    DOCS_DEPLOY_SERVER_USER: "$DOCS_SERVER_USER"
    DOCS_DEPLOY_PATH: "$DOCS_PATH"
    DOCS_DEPLOY_URL_BASE: "https://$DOCS_PREVIEW_SERVER_URL/docs/esp-idf"

# stage: post_deploy
deploy_docs_production:
  # The DOCS_PROD_* variables used by this job are "Protected" so these branches must all be marked "Protected" in Gitlab settings
  extends:
    - .deploy_docs_template
    - .doc-rules:build:docs-full-prod
  stage: post_deploy
  dependencies:  # set dependencies to null to avoid missing artifacts issue
  needs: # ensure runs after push_to_github succeeded
    - build_docs_html_full_prod
    - build_docs_pdf_prod
    - job: push_to_github
      artifacts: false
  variables:
    TYPE: "preview"
    DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PROD_DEPLOY_KEY"
    DOCS_DEPLOY_SERVER: "$DOCS_PROD_SERVER"
    DOCS_DEPLOY_SERVER_USER: "$DOCS_PROD_SERVER_USER"
    DOCS_DEPLOY_PATH: "$DOCS_PROD_PATH"
    DOCS_DEPLOY_URL_BASE: "https://docs.espressif.com/projects/esp-idf"
    DEPLOY_STABLE: 1

check_doc_links:
  extends:
    - .build_docs_template
    - .doc-rules:build:docs-full-prod
  stage: post_deploy
  needs:
    - job: deploy_docs_production
      artifacts: false
  tags: ["build", "amd64", "internet"]
  artifacts:
    when: always
    paths:
      - docs/_build/*/*/*.txt
      - docs/_build/*/*/linkcheck/*.txt
    expire_in: 1 week
  allow_failure: true
  script:
    - cd docs
    - build-docs -t $DOCTGT -l $DOCLANG linkcheck