esp-idf/.gitlab/ci/docs.yml
2021-09-06 09:11:17 +08:00

226 lines
6.3 KiB
YAML

.patterns-docs: &patterns-docs
- ".gitlab/ci/docs.yml"
- "docs/**/*"
- "components/**/*.h"
- "components/**/Kconfig*"
- "components/**/CMakeList.txt"
- "components/**/sdkconfig*"
- "tools/kconfig_new/**/*"
- "CONTRIBUTING.rst"
.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_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_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_full
- <<: *if-dev-push
changes: *patterns-docs
# stage: pre_check
check_readme_links:
extends:
- .pre_check_job_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_job_template
- .doc-rules:build:docs
script:
- cd docs
- ./check_lang_folder_sync.sh
.build_docs_template:
image: $ESP_IDF_DOC_ENV_IMAGE
variables:
PYTHON_VER: 3.6.13
tags:
- build_docs
dependencies: []
script:
- cd docs
- pip install -r requirements.txt
- build-docs -t $DOCTGT -bs $DOC_BUILDERS -l $DOCLANG build
parallel:
matrix:
- DOCLANG: ["en", "zh_CN"]
DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32c3"]
check_docs_gh_links:
image: $ESP_IDF_DOC_ENV_IMAGE
variables:
PYTHON_VER: 3.6.13
extends:
- .pre_check_job_template
- .doc-rules:build:docs
script:
- cd docs
- pip install -r requirements.txt
- 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-protected
- <<: *if-label-docs_full
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_full
when: never
- <<: *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"
DOCS_FAST_BUILD: "yes"
build_docs_pdf:
extends:
- .build_docs_build_stage_template
rules:
- <<: *if-protected
- <<: *if-label-docs_full
artifacts:
when: always
paths:
- docs/_build/*/*/latex/*
expire_in: 4 days
variables:
DOC_BUILDERS: "latex"
.deploy_docs_template:
extends:
- .before_script_no_sync_submodule
image: $ESP_IDF_DOC_ENV_IMAGE
variables:
PYTHON_VER: 3.6.13
stage: test_deploy
tags:
- deploy
- shiny
variables:
DOCS_BUILD_DIR: "${IDF_PATH}/docs/_build/"
PYTHONUNBUFFERED: 1
dependencies: []
script:
- add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
- export GIT_VER=$(git describe --always)
- pip install -r docs/requirements.txt
- deploy-docs
# stage: test_deploy
deploy_docs_preview:
extends:
- .deploy_docs_template
rules:
- <<: *if-label-build_docs
- <<: *if-label-docs
dependencies:
- build_docs_html_fast
- build_docs_html_full
- build_docs_pdf
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://$CI_DOCKER_REGISTRY/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"
check_doc_links:
extends:
- .build_docs_template
- .rules:protected
stage: post_deploy
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
- pip install -r requirements.txt
# At the moment this check will always fail due to multiple known limitations, ignore result
- build-docs -t $DOCTGT -l $DOCLANG linkcheck || { echo "THERE ARE ISSUES DUE TO KNOWN LIMITATIONS, PLEASE FIX THEM. Nowadays we're ignored them to pass pipeline."; true; }