Merge branch 'ci/granular_doc_build' into 'master'

docs: add a more granular trigger for build docs jobs

See merge request espressif/esp-idf!22632

.gitlab/ci/README.md

@@ -52,7 +52,7 @@
 - `custom_test[_esp32/esp32s2/...]`
 - `docker`
 - `docs`
-- `docs_fast`, triggers a fast docs build, not a full build which is the CI default. This skips PDF build as well as doxygen APIs, reducing the build time by 90+%.
+- `docs_full`, triggers a full docs build, regardless of files changed
 - `example_test[_esp32/esp32s2/...]`
 - `fuzzer_test`
 - `host_test`

.gitlab/ci/docs.yml

@@ -1,14 +1,19 @@
-.patterns-docs: &patterns-docs
+.patterns-docs-full: &patterns-docs-full
   - ".gitlab/ci/docs.yml"
   - "docs/**/*"
+  - "**/*.rst"
+  - "CONTRIBUTING.rst"
+
+.patterns-docs-partial: &patterns-docs-partial
   - "components/**/*.h"
   - "components/**/Kconfig*"
   - "components/**/CMakeList.txt"
   - "components/**/sdkconfig*"
-  - "**/*.rst"
   - "tools/tools.json"
   - "tools/idf_tools.py"
-  - "CONTRIBUTING.rst"
+
+.patterns-example-readme: &patterns-example-readme
+  - "examples/**/*.md"
 
 .patterns-docs-preview: &patterns-docs-preview
   - "docs/**/*"
@@ -22,43 +27,49 @@
 .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-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:
+.doc-rules:build:docs-full:
   rules:
     - <<: *if-protected
     - <<: *if-label-build_docs
-    - <<: *if-label-docs
-    - <<: *if-label-docs_fast
+    - <<: *if-label-docs_full
+    - <<: *if-dev-push
+      changes: *patterns-docs-full
+
+.doc-rules:build:docs-partial:
+  rules:
     - <<: *if-dev-push
-      changes: *patterns-docs
+      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
+    - .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
   dependencies: []
@@ -74,36 +85,17 @@ check_docs_gh_links:
   image: $ESP_IDF_DOC_ENV_IMAGE
   extends:
     - .pre_check_template
-    - .doc-rules:build:docs
+    - .doc-rules:build:docs-full
   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
+    - .build_docs_template
+    - .doc-rules:build:docs-full
   artifacts:
     when: always
     paths:
@@ -113,11 +105,10 @@ build_docs_html_full:
   variables:
     DOC_BUILDERS: "html"
 
-build_docs_html_fast:
+build_docs_html_partial:
   extends:
-    - .build_docs_build_stage_template
-  rules:
-    - <<: *if-label-docs_fast
+    - .build_docs_template
+    - .doc-rules:build:docs-partial
   artifacts:
     when: always
     paths:
@@ -126,19 +117,17 @@ build_docs_html_fast:
     expire_in: 4 days
   variables:
     DOC_BUILDERS: "html"
-    DOCS_FAST_BUILD: "yes"
+  parallel:
+    matrix:
+      - DOCLANG: "en"
+        DOCTGT: "esp32"
+      - DOCLANG: "zh_CN"
+        DOCTGT: "esp32c6"
 
 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
+    - .build_docs_template
+    - .doc-rules:build:docs-full
   artifacts:
     when: always
     paths:
@@ -167,11 +156,11 @@ deploy_docs_preview:
     - .deploy_docs_template
   rules:
     - <<: *if-label-build_docs
-    - <<: *if-label-docs
+    - <<: *if-label-docs_full
     - <<: *if-dev-push
       changes: *patterns-docs-preview
   needs:
-    - job: build_docs_html_fast
+    - job: build_docs_html_partial
       optional: true
     - job: build_docs_html_full
       optional: true