update doc build ci

1. remove gen_dxd, link_roles, local_util
2. use esp-docs to build

Author: lijunru-hub

.gitlab-ci.yml

@@ -1,8 +1,8 @@
 stages:
+  - build_doc
   - pre_check
   - build
   - target_test
-  - build_doc
   - deploy
 
 workflow:

.gitlab/ci/docs.yml

@@ -1,36 +1,33 @@
-build_docs:
-  extends:
-    - .rules:build:docs
+variables:
+  ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.2:1-1"
+
+.build_docs_template:
+  image: $ESP_IDF_DOC_ENV_IMAGE
   stage: build_doc
-  image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:v7
   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
-      # Chinese version of documentation
-      - docs/zh_CN/doxygen-warning-log.txt
-      - docs/zh_CN/sphinx-warning-log.txt
-      - docs/zh_CN/sphinx-warning-log-sanitized.txt
-      - docs/zh_CN/_build/html
-    expire_in: 1 mos
+  dependencies: []
   script:
-    - source /opt/pyenv/activate && pyenv global 3.6.10
-    - pip install "setuptools<57.5.0"
-    - pip install "funcparserlib==0.3.6"
-    - /opt/pyenv/pyenv-1.2.16/versions/3.6.10/bin/python -m pip install --user -r docs/requirements.txt
     - cd docs
+    - python -m pip install -r requirements.txt 
+    - build-docs -t $DOCTGT -bs $DOC_BUILDERS -l $DOCLANG build
     - ./check_lang_folder_sync.sh
-    - cd en
-    - make gh-linkcheck
-    - make html
-    - ../check_doc_warnings.sh
-    - cd ../zh_CN
-    - make gh-linkcheck
-    - make html
-    - ../check_doc_warnings.sh
+
+build_docs_html:
+  extends:
+    - .build_docs_template
+    - .rules:build:docs
+  artifacts:
+    when: always
+    paths:
+      - docs/_build/*/*/*.txt
+      - docs/_build/*/*/html/*
+    expire_in: 4 days
+  variables:
+    DOC_BUILDERS: "html"
+  parallel:
+    matrix:
+      - DOCLANG: "en"
+        DOCTGT: "esp32"
+      - DOCLANG: "zh_CN"
+        DOCTGT: "esp32"

docs/Doxyfile

@@ -21,25 +21,25 @@ PROJECT_NAME = "ESP IoT Solution Guide"
 ## and used to include in API reference documentation
 
 INPUT = \
-    ../../components/bus/include/i2c_bus.h \
-    ../../components/bus/include/spi_bus.h \
-    ../../components/bus/include/i2s_lcd_driver.h \
-    ../../components/sensors/sensor_hub/include/sensor_type.h \
-    ../../components/sensors/sensor_hub/include/iot_sensor_hub.h \
-    ../../components/sensors/sensor_hub/include/hal/humiture_hal.h \
-    ../../components/sensors/sensor_hub/include/hal/imu_hal.h \
-    ../../components/sensors/sensor_hub/include/hal/light_sensor_hal.h \
-    ../../components/motor/servo/include/iot_servo.h \
-    ../../components/audio/pwm_audio/include/pwm_audio.h \
-    ../../components/audio/dac_audio/include/dac_audio.h \
-    ../../components/display/screen/screen_driver.h \
-    ../../components/display/screen/interface_driver/scr_interface_driver.h \
-    ../../components/display/touch_panel/touch_panel.h \
-    ../../components/led/led_indicator/include/led_indicator.h \
-    ../../components/button/include/iot_button.h \
-    ../../components/openai/include/OpenAI.h \
-    ../../components/usb/usb_stream/include/usb_stream.h \
-    ../../components/knob/iot_knob.h \
+    $(PROJECT_PATH)/components/bus/include/i2c_bus.h \
+    $(PROJECT_PATH)/components/bus/include/spi_bus.h \
+    $(PROJECT_PATH)/components/bus/include/i2s_lcd_driver.h \
+    $(PROJECT_PATH)/components/sensors/sensor_hub/include/sensor_type.h \
+    $(PROJECT_PATH)/components/sensors/sensor_hub/include/iot_sensor_hub.h \
+    $(PROJECT_PATH)/components/sensors/sensor_hub/include/hal/humiture_hal.h \
+    $(PROJECT_PATH)/components/sensors/sensor_hub/include/hal/imu_hal.h \
+    $(PROJECT_PATH)/components/sensors/sensor_hub/include/hal/light_sensor_hal.h \
+    $(PROJECT_PATH)/components/motor/servo/include/iot_servo.h \
+    $(PROJECT_PATH)/components/audio/pwm_audio/include/pwm_audio.h \
+    $(PROJECT_PATH)/components/audio/dac_audio/include/dac_audio.h \
+    $(PROJECT_PATH)/components/display/screen/screen_driver.h \
+    $(PROJECT_PATH)/components/display/screen/interface_driver/scr_interface_driver.h \
+    $(PROJECT_PATH)/components/display/touch_panel/touch_panel.h \
+    $(PROJECT_PATH)/components/led/led_indicator/include/led_indicator.h \
+    $(PROJECT_PATH)/components/button/include/iot_button.h \
+    $(PROJECT_PATH)/components/openai/include/OpenAI.h \
+    $(PROJECT_PATH)/components/usb/usb_stream/include/usb_stream.h \
+    $(PROJECT_PATH)/components/knob/iot_knob.h \
 
 ## Get warnings for functions that have no documentation for their parameters or return value
 ##
@@ -84,3 +84,7 @@ QUIET = YES
 ##
 WARN_LOGFILE = "doxygen-warning-log.txt"
 
+## Enable Section Tags for conditional documentation
+##
+ENABLED_SECTIONS += DOC_EXCLUDE_HEADER_SECTION  ## To conditionally remove doc sections from IDF source files without affecting documentation in upstream files.
+ENABLED_SECTIONS += DOC_SINGLE_GROUP            ## To conditionally remove groups from the documentation and create a 'flat' document without affecting documentation in upstream files.

docs/README.md

@@ -0,0 +1,37 @@
+# Documentation Source Folder
+
+This folder contains source files of **ESP-IDF documentation** available in [English](https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/index.html) and [中文](https://docs.espressif.com/projects/espressif-esp-iot-solution/zh_CN/latest/index.html).
+
+The sources do not render well in GitHub and some information is not visible at all.
+
+Use actual documentation generated within about 20 minutes on each commit:
+
+# Hosted Documentation
+
+* English: https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/index.html
+* 中文: https://docs.espressif.com/projects/espressif-esp-iot-solution/zh_CN/latest/index.html
+
+The above URLs are all for the master branch latest version. Click the drop-down in the bottom left to choose a stable version or to download a PDF.
+
+# Building Documentation
+
+The documentation is built using the python package `esp-docs`, which can be installed by running `pip install esp-docs`. Running `build-docs --help` will give a summary of available options. For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md
+
+If you need to compile html files in this repository, you can use:
+
+```
+build-docs -t esp32 -l zh_CN -bs html
+build-docs -t esp32 -l en -bs html
+```
+
+# Preview
+
+To preview the compiled html files locally:
+
+* Start a local web page
+    
+    ```
+    python3 -m http.server 8000 --directory _build/zh_CN/esp32/html 
+    ```
+
+* Enter the URL: http://localhost:8000/ for online preview