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

# stage: pre_check
check_readme_links:
  extends:
    - .pre_check_job_template
    - .rules:build:docs
  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
    - .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
    - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 pip install -r requirements.txt
    - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 ./build_docs.py -bs $DOC_BUILDERS -l $DOCLANG -t $DOCTGT build
  parallel:
    matrix:
      - DOCLANG: ["en", "zh_CN"]
        DOCTGT: ["esp32", "esp32s2", "esp32c3"]

check_docs_gh_links:
  extends:
    - .pre_check_job_template
    - .build_docs_template
    - .rules:build:docs
  script:
    - cd docs
    - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 pip install -r requirements.txt
    - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 ./build_docs.py 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
    - .rules:build:docs
  stage: build_doc
  needs:
    - job: check_docs_lang_sync
      artifacts: false
    - job: check_docs_gh_links
      artifacts: false

build_docs_html:
  extends:
    - .build_docs_build_stage_template
  artifacts:
    when: always
    paths:
      - docs/_build/*/*/*.txt
      - docs/_build/*/*/html/*
    expire_in: 4 days
  variables:
    DOC_BUILDERS: "html"

build_docs_pdf:
  extends:
    - .build_docs_build_stage_template
    - .rules:build:docs:label-only
  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
  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)
    - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 ${IDF_PATH}/tools/ci/deploy_docs.py

# stage: test_deploy
deploy_docs_preview:
  extends:
    - .deploy_docs_template
    - .rules:build:docs:label-only-preview
  dependencies:  # set dependencies to null to avoid missing artifacts issue
  needs:
    - build_docs_html
    - 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:build:docs-production
  stage: post_deploy
  dependencies:  # set dependencies to null to avoid missing artifacts issue
  needs: # ensure runs after push_to_github succeeded
    - build_docs_html
    - 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
    - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 pip install -r requirements.txt
    # At the moment this check will always fail due to multiple known limitations, ignore result
    - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 ./build_docs.py -l $DOCLANG -t $DOCTGT linkcheck || { echo "THERE ARE ISSUES DUE TO KNOWN LIMITATIONS, PLEASE FIX THEM. Nowadays we're ignored them to pass pipeline."; true; }