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

232 lines
6.3 KiB
YAML

.patterns-docs: &patterns-docs
- ".gitlab/ci/docs.yml"
- "docs/**/*"
- "components/**/*.h"
- "components/**/Kconfig*"
- "components/**/CMakeList.txt"
- "components/**/sdkconfig*"
- "**/*.rst"
- "tools/tools.json"
- "tools/idf_tools.py"
- "CONTRIBUTING.rst"
.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-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: &if-label-docs
if: '$BOT_LABEL_DOCS || $CI_MERGE_REQUEST_LABELS =~ /^(?:[^,\n\r]+,)*docs(?:,[^,\n\r]+)*$/i'
.if-label-docs_fast: &if-label-docs_fast
if: '$BOT_LABEL_DOCS_FAST || $CI_MERGE_REQUEST_LABELS =~ /^(?:[^,\n\r]+,)*docs_fast(?:,[^,\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_PIPELINE_SOURCE == "push" || $CI_PIPELINE_SOURCE == "merge_request_event")'
.doc-rules:build:docs:
rules:
- <<: *if-protected
- <<: *if-label-build_docs
- <<: *if-label-docs
- <<: *if-label-docs_fast
- <<: *if-dev-push
changes: *patterns-docs
# stage: pre_check
check_readme_links:
extends:
- .pre_check_template
tags: ["build", "amd64", "internet"]
allow_failure: true
script:
- python ${IDF_PATH}/tools/ci/check_readme_links.py
check_docs_lang_sync:
extends:
- .pre_check_template
- .doc-rules:build:docs
script:
- cd docs
- ./check_lang_folder_sync.sh
.build_docs_template:
image: $ESP_IDF_DOC_ENV_IMAGE
tags:
- build_docs
dependencies: []
script:
- 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"]
check_docs_gh_links:
image: $ESP_IDF_DOC_ENV_IMAGE
extends:
- .pre_check_template
- .doc-rules:build:docs
script:
- cd docs
- build-docs gh-linkcheck
# stage: build_doc
# Add this stage to let the build_docs job run in parallel with build
.build_docs_build_stage_template:
extends:
- .build_docs_template
stage: build_doc
needs:
- job: check_docs_lang_sync
artifacts: false
- job: check_docs_gh_links
artifacts: false
# 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_build_stage_template
rules:
- <<: *if-label-docs_fast
when: never
- <<: *if-protected
- <<: *if-label-build_docs
- <<: *if-label-docs
- <<: *if-dev-push
changes: *patterns-docs
artifacts:
when: always
paths:
- docs/_build/*/*/*.txt
- docs/_build/*/*/html/*
expire_in: 4 days
variables:
DOC_BUILDERS: "html"
build_docs_html_fast:
extends:
- .build_docs_build_stage_template
rules:
- <<: *if-label-docs_fast
artifacts:
when: always
paths:
- docs/_build/*/*/*.txt
- docs/_build/*/*/html/*
expire_in: 4 days
variables:
DOC_BUILDERS: "html"
DOCS_FAST_BUILD: "yes"
build_docs_pdf:
extends:
- .build_docs_build_stage_template
rules:
- <<: *if-label-docs_fast
when: never
- <<: *if-protected
- <<: *if-label-build_docs
- <<: *if-label-docs
- <<: *if-dev-push
changes: *patterns-docs
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
- <<: *if-dev-push
changes: *patterns-docs-preview
needs:
- job: build_docs_html_fast
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
rules:
- <<: *if-protected-no_label
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
- build_docs_pdf
- 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
rules:
- <<: *if-protected-no_label
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