chore(ci): Build documents at CI always.

.gitlab-ci.yml

@@ -73,3 +73,31 @@ push_master_to_github:
     # (aka objectname) at tip of each branch, and if any SHAs match then it checks out the local branch
     # and then pushes that ref to a corresponding github branch
     - eval $(git for-each-ref --shell bash --format 'if [ $CI_COMMIT_SHA == %(objectname) ]; then git checkout -B %(refname:strip=3); git push --follow-tags github %(refname:strip=3); fi;' $GITHUB_PUSH_REFS)
+
+build_docs:
+  stage: build
+  image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
+  tags:
+    - build_docs
+  artifacts:
+    when: always
+    paths:
+      # English version of documentation
+      - docs/en/doxygen-warning-log.txt
+      - docs/en/sphinx-warning-log.txt
+      - docs/en/sphinx-warning-log-sanitized.txt
+      - docs/en/_build/html
+      - docs/sphinx-err-*
+    expire_in: 1 day
+  only:
+    variables:
+      - $BOT_TRIGGER_WITH_LABEL == null
+      - $BOT_LABEL_BUILD
+      - $BOT_LABEL_BUILD_DOCS
+      - $BOT_LABEL_REGULAR_TEST
+  script:
+    - cd docs
+    - cd en
+    - make gh-linkcheck
+    - make html
+    - ../check_doc_warnings.sh

docs/check_doc_warnings.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+#
+# Check for Documentation warnings:
+# doxygen-warning-log.txt should be an empty file
+# sphinx-warning-log.txt should only contain (fuzzy) matches to ../sphinx-known-warnings.txt
+RESULT=0
+STARS='***************************************************'
+
+if [ -s doxygen-warning-log.txt ]; then
+    echo "$STARS"
+    echo "Build failed due to doxygen warnings:"
+    cat doxygen-warning-log.txt
+    echo "$STARS"
+    RESULT=1
+fi
+
+# Remove escape characters, file paths, line numbers from
+# the Sphinx warning log
+# (escape char removal from https://www.commandlinefu.com/commands/view/6141/remove-color-codes-special-characters-with-sed
+sed -r 's:\x1B\[[0-9;]*[mK]::g' sphinx-warning-log.txt | \
+    sed -E "s/.*\/(.*):[0-9]+:/\1:line:/" > sphinx-warning-log-sanitized.txt
+
+# diff sanitized warnings, ignoring lines which only appear in ../sphinx-known-warnings.txt
+
+# format is to display only lines new or changed in second argument
+DIFF_FORMAT="--unchanged-line-format= --old-line-format= --new-line-format=%L"
+
+SPHINX_WARNINGS=$(diff $DIFF_FORMAT ../sphinx-known-warnings.txt sphinx-warning-log-sanitized.txt)
+if ! [ -z "$SPHINX_WARNINGS" ]; then
+    echo "$STARS"
+    echo "Build failed due to new/different Sphinx warnings:"
+    echo "$SPHINX_WARNINGS"
+    echo "$STARS"
+    RESULT=1
+    echo "(Check files ../sphinx-known-warnings.txt and sphinx-warning-log.txt for full details.)"
+fi
+
+exit $RESULT
+

docs/sphinx-known-warnings.txt

@@ -0,0 +1,83 @@
+# File contains known/allowed Sphinx warnings.
+#
+# Build will fail if sphinx-warning-log.txt contains any lines
+# which are not in this file. Lines are pre-sanitized by
+# check_doc_warnings.sh to remove formatting, paths and line numbers.
+#
+# Warnings in this file must be in the same overall order as the log file.
+#
+
+#
+# Sphinx known issue https://github.com/sphinx-doc/sphinx/issues/2683
+#
+# Note: warnings below will be gone after upgrade
+#       to the following package==version
+#
+#       sphinx==1.8.4
+#       breathe==4.11.1
+#
+esp_a2dp_api.inc:line: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
+  union esp_a2d_mcc_t::@1  esp_a2d_mcc_t::cie
+  ---------------------^
+esp_bt_defs.inc:line: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
+  union esp_bt_uuid_t::@0  esp_bt_uuid_t::uuid
+  ---------------------^
+
+#
+# Breathe known issue: https://github.com/michaeljones/breathe/issues/405
+# Sphinx known issue: https://github.com/sphinx-doc/sphinx/pull/5901
+#
+# Note: warnings below have been identified after upgrade
+#       to the following package==version
+#
+#       sphinx==1.8.4
+#       breathe==4.11.1
+#
+ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size)
+ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
+ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us)
+README.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
+#
+# Issue present only when building on msys2 / mingw32 START >>>
+#
+esp_spp_api.inc:line: WARNING: Error in type declaration.
+If typedef-like declaration:
+  Type must be either just a name or a typedef-like declaration.
+  If just a name:
+    Error in declarator or parameters and qualifiers
+    Invalid definition: Expected identifier in nested name, got keyword: void [error at 4]
+      void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+      ----^
+  If typedef-like declaration:
+    Error in declarator
+    If pointer to member declarator:
+      Invalid definition: Expected identifier in nested name. [error at 4]
+        void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+        ----^
+    If declId, parameters, and qualifiers:
+      Invalid definition: Expected identifier in nested name. [error at 4]
+        void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+        ----^
+    If parenthesis in noptr-declarator:
+      Error in declarator or parameters and qualifiers
+      If pointer to member declarator:
+        Invalid definition: Expected identifier in nested name. [error at 5]
+          void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+          -----^
+      If declarator-id:
+        Invalid definition: Expected identifier in nested name. [error at 5]
+          void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+          -----^
+If type alias or template alias:
+  Invalid definition: Expected identifier in nested name, got keyword: void [error at 4]
+    void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+    ----^
+#
+# Issue present only when building on msys2 / mingw32 END <<<
+#
+spi_master.inc:line: WARNING: Duplicate declaration, struct spi_transaction_t spi_transaction_t
+spi_slave.inc:line: WARNING: Duplicate declaration, struct spi_slave_transaction_t spi_slave_transaction_t
+wear-levelling.rst:line: WARNING: Duplicate declaration, bool esp_vfs_fat_mount_config_t::format_if_mount_failed
+wear-levelling.rst:line: WARNING: Duplicate declaration, int esp_vfs_fat_mount_config_t::max_files
+wear-levelling.rst:line: WARNING: Duplicate declaration, size_t esp_vfs_fat_mount_config_t::allocation_unit_size
+wear-levelling.rst:line: WARNING: Duplicate declaration, esp_vfs_fat_mount_config_t