ci: Adds documentation build

- Adds documentation build and deploy - Removes QEMU test as it is outdated
2025-10-01 17:41:37 +02:00 · 2025-09-23 15:17:59 +02:00
parent 2925288e51
commit 2b33476c3f
19 changed files with 404 additions and 166 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -31,6 +31,82 @@
 # Debug files
 *.dSYM/
 *.su
-build
-examples/**/build
-examples/**/sdkconfig*
+
+# ESP-IDF Build System
+build/
+sdkconfig
+sdkconfig.old
+dependencies.lock
+managed_components/
+
+# ESP-IDF build directories (but not source directories like build_test)
+**/build/
+**/build_esp32*/
+**/build_esp32c*/
+**/build_esp32s*/
+**/build_esp32h*/
+**/build_esp32p*/
+**/build_linux*/
+
+# Examples and test app builds
+examples/**/build/
+examples/**/build_esp32*/
+examples/**/build_esp32c*/
+examples/**/build_esp32s*/
+examples/**/build_esp32h*/
+examples/**/build_esp32p*/
+examples/**/sdkconfig
+examples/**/sdkconfig.old
+examples/**/dependencies.lock
+examples/**/managed_components/
+
+# Test application builds (specific build directories, not source)
+test/apps/**/build/
+test/apps/**/build_esp32*/
+test/apps/**/build_esp32c*/
+test/apps/**/build_esp32s*/
+test/apps/**/build_esp32h*/
+test/apps/**/build_esp32p*/
+test/apps/**/sdkconfig
+test/apps/**/sdkconfig.old
+test/apps/**/dependencies.lock
+test/apps/**/managed_components/
+
+# Host test builds
+test/host/build/
+test/host/sdkconfig
+test/host/sdkconfig.old
+test/host/dependencies.lock
+test/host/managed_components/
+
+# idf-ci generated files
+app_info_*.txt
+size_info_*.txt
+compile_commands.json
+*.log
+
+# Python cache and environments
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+.cache/
+
+# Coverage and test results
+**/coverage.xml
+**/coverage.html
+**/junit.xml
+**/pytest_*.xml
+**/test_results_*.xml
+
+# Documentation builds
+docs/_build/
+docs/build/
+
+# Distribution/packaging
+dist/
+build/
+*.egg-info/
+
+# CI/CD artifacts
+build_child_pipeline.yml
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,6 +1,7 @@
 stages:
    - build
    - test
+    - test_deploy
    - deploy

 variables:
@@ -73,40 +74,8 @@ build_and_host_test:
        - idf.py build
        - build/host_mqtt_client_test.elf

-build_and_test_qemu:
-    stage: build
-    image: ${CI_DOCKER_REGISTRY}/qemu-v5.1:1-20220802
-    tags:
-        - build
-        - internet
-    dependencies: []
-    script:
-        - export IDF_PATH=$CI_PROJECT_DIR/esp-idf
-        - git clone "${IDF_REPO}"
-        # switch to IDF and setup the tools
-        - $MQTT_PATH/ci/set_idf.sh release/v5.1
-        - $IDF_PATH/tools/idf_tools.py install-python-env
-        - cd $IDF_PATH && tools/idf_tools.py --non-interactive install && eval "$(tools/idf_tools.py --non-interactive export)"
-        # Remove `debug_backend` and Add `paho-mqtt` to the required packages
-        - sed '/debug_backend/d;/pygobject/d' $IDF_PATH/tools/requirements/requirements.ttfw.txt > requirements.txt
-        - python -m pip install -r requirements.txt
-        - python -m pip install paho-mqtt
-        - $MQTT_PATH/ci/set_mqtt.sh $CI_COMMIT_SHA
-        # build publish-connect stress test, setup test parameters
-        - cd tools/test_apps/protocols/mqtt/publish_connect_test && cat sdkconfig.qemu | $IDF_PATH/tools/ci/envsubst.py > sdkconfig.defaults && idf.py build
-        - export TEST_PATH=`pwd` && export MQTT_PUBLISH_TEST=1
-        - export PYTHONPATH="$IDF_PATH/tools:$IDF_PATH/tools/ci/python_packages"
-        # run test (with environment->qemu)
-        - cd $IDF_PATH/tools/ci/python_packages/tiny_test_fw/bin
-        # use more relaxed criteria with QEMU tests
-        - export MQTT_PUBLISH_MSG_len_0=0   MQTT_PUBLISH_MSG_repeat_0=5
-        - export MQTT_PUBLISH_MSG_len_1=2   MQTT_PUBLISH_MSG_repeat_1=50
-        - export MQTT_PUBLISH_MSG_len_2=128 MQTT_PUBLISH_MSG_repeat_2=2
-        - export MQTT_PUBLISH_MSG_len_3=20  MQTT_PUBLISH_MSG_repeat_3=20
-        - python Runner.py $TEST_PATH -c $MQTT_PATH/ci/publish_connect_mqtt_qemu.yml -e $TEST_PATH/env.yml
-
 check_remotes_sync:
-    stage: test
+    stage: test_deploy
    image: espressif/idf:latest
    tags:
        - build
@@ -134,3 +103,6 @@ push_master_to_github:
    script:
        - *add_gh_key_remote
        - git push github HEAD:${CI_COMMIT_REF_NAME}
+
+include:
+    - local: ".gitlab/ci/docs.yml"
--- a/.gitlab/ci/docs.yml
+++ b/.gitlab/ci/docs.yml
@@ -0,0 +1,85 @@
+variables:
+  # System environment
+  ESP_DOCS_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.4:1-1"
+  ESP_DOCS_PATH: "$CI_PROJECT_DIR"
+
+docs_build:
+    stage: build
+    image: $ESP_DOCS_ENV_IMAGE
+    tags:
+        - build_docs
+    variables:
+        # Set Python buffering for better CI output
+        PYTHONUNBUFFERED: 1
+        TYPE: "preview"
+        DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
+    artifacts:
+        when: always
+        paths:
+            - docs/_build/*/*/*.txt
+            - docs/_build/*/*/html/*
+        expire_in: 4 days
+    before_script:
+        # Install ESP-IDF documentation build tool
+        - pip install -U pip
+        - pip install esp-docs linuxdoc
+    script:
+        - cd docs
+        - build-docs -t esp32 -l en
+    rules:
+        - if: $CI_COMMIT_REF_NAME == "master"
+        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+
+.deploy_docs_template:
+  image: $ESP_DOCS_ENV_IMAGE
+  variables:
+    DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
+    PYTHONUNBUFFERED: 1
+    # ensure all tags are fetched, need to know the latest/stable tag for the docs
+    GIT_STRATEGY: clone
+    GIT_DEPTH: 0
+  stage: test_deploy
+  tags:
+    - brew
+    - amd64
+  script:
+    - source ${CI_PROJECT_DIR}/.gitlab/ci/utils.sh
+    # ensure all tags are fetched, need to know the latest/stable tag for the docs
+    - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
+    - export GIT_VER=$(git describe --always ${PIPELINE_COMMIT_SHA} --)
+    - pip install esp-docs
+    - deploy-docs
+
+deploy_docs_preview:
+  extends:
+    - .deploy_docs_template
+  except:
+    refs:
+      - master
+  needs:
+    - docs_build
+  variables:
+    TYPE: "preview"
+    DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
+    DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PREVIEW_PRIVATEKEY"
+    DOCS_DEPLOY_SERVER: "$DOCS_PREVIEW_SERVER"
+    DOCS_DEPLOY_SERVER_USER: "$DOCS_PREVIEW_SERVER_USER"
+    DOCS_DEPLOY_PATH: "$DOCS_PREVIEW_PATH"
+    DOCS_DEPLOY_URL_BASE: "$DOCS_PREVIEW_URL_BASE"
+
+deploy_docs_prod:
+  extends:
+    - .deploy_docs_template
+  stage: deploy
+  only:
+    refs:
+      - master
+  needs:
+    - docs_build
+  variables:
+    TYPE: "production"
+    DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PROD_PRIVATEKEY"
+    DOCS_DEPLOY_SERVER: "$DOCS_PROD_SERVER"
+    DOCS_DEPLOY_SERVER_USER: "$DOCS_PROD_SERVER_USER"
+    DOCS_DEPLOY_PATH: "$DOCS_PROD_PATH"
+    DOCS_DEPLOY_URL_BASE: "$DOCS_PROD_URL_BASE"
--- a/.gitlab/ci/utils.sh
+++ b/.gitlab/ci/utils.sh
@@ -0,0 +1,26 @@
+function add_ssh_keys() {
+  local key_string="${1}"
+  mkdir -p ~/.ssh
+  chmod 700 ~/.ssh
+  echo -n "${key_string}" >~/.ssh/id_rsa_base64
+  base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 >~/.ssh/id_rsa
+  chmod 600 ~/.ssh/id_rsa
+}
+function add_doc_server_ssh_keys() {
+  local key_string="${1}"
+  local server_url="${2}"
+  local server_user="${3}"
+  add_ssh_keys "${key_string}"
+  echo -e "Host ${server_url}\n\tStrictHostKeyChecking no\n\tUser ${server_user}\n" >>~/.ssh/config
+}
+
+function add_github_remote() {
+  local key_string="${1}"
+  local remote_url="${2}"
+  add_ssh_keys "${key_string}"
+  if ! grep -q "Host github.com" ~/.ssh/config 2>/dev/null; then
+    printf "Host github.com\n\tStrictHostKeyChecking no\n" >>~/.ssh/config
+  fi
+  git remote remove github || true
+  git remote add github "${remote_url}"
+}
--- a/ci/build-test-rules.yml
+++ b/ci/build-test-rules.yml
@@ -1,11 +0,0 @@
-# Documentation: .gitlab/ci/README.md#manifest-file-to-control-the-buildtest-apps
-
-examples/protocols:
-  enable:
-    - if: IDF_TARGET in ["esp32"]
-
-examples/protocols/mqtt/ssl_ds:
-  disable:
-    - if: SOC_DIG_SIGN_SUPPORTED != 1
-      temporary: false
-      reason: DS not present
--- a/ci/build_examples.sh
+++ b/ci/build_examples.sh
@@ -1,22 +0,0 @@
-#!/usr/bin/env bash
-
-# build mqtt examples with make if $1=="make", with cmake otherwise
-set -o errexit # Exit if command failed.
-
-if [ -z $IDF_PATH ] ; then
-    echo "Mandatory variables undefined"
-    exit 1;
-fi;
-
-examples="tcp ssl ssl_mutual_auth ws wss"
-for i in $examples; do
-    echo "Building MQTT example $i"
-    cd $IDF_PATH/examples/protocols/mqtt/$i
-    if [[ "$1" = "make" ]]; then
-        make defconfig
-        make -j 4
-    else
-        rm -rf build sdkconfig
-        idf.py build
-    fi;
-done
--- a/ci/idf_build_apps.toml
+++ b/ci/idf_build_apps.toml
@@ -1,2 +0,0 @@
-build_dir = "$GITHUB_WORKSPACE/build_@t_@n"
-config="sdkconfig.ci"
--- a/ci/modify_for_legacy_idf.sh
+++ b/ci/modify_for_legacy_idf.sh
@@ -1,33 +0,0 @@
-#!/usr/bin/env bash
-
-if [[ -z $1 ]]; then
-    LATEST_IDF=master
-else
-    LATEST_IDF=$1
-fi
-
-# This snipped prepares environment for using esp-mqtt repository separately from idf -- legacy use before IDFv3.2
-#
-esp_mqtt_path=`pwd`
-mkdir -p ${esp_mqtt_path}/examples
-pushd
-cd $IDF_PATH
-former_commit_id=`git rev-parse HEAD`
-git checkout ${LATEST_IDF}
-
-for example in tcp; do
-    cp -r $IDF_PATH/examples/protocols/mqtt/${example} ${esp_mqtt_path}/examples
-    echo 'EXTRA_COMPONENT_DIRS += $(PROJECT_PATH)/../../../' >   ${esp_mqtt_path}/examples/${example}/Makefile
-    cat $IDF_PATH/examples/protocols/mqtt/${example}/Makefile >> ${esp_mqtt_path}/examples/${example}/Makefile
-    echo "CONFIG_MQTT_TRANSPORT_SSL=" >> ${esp_mqtt_path}/examples/${example}/sdkconfig.defaults
-    echo "CONFIG_MQTT_TRANSPORT_WEBSOCKET=" >> ${esp_mqtt_path}/examples/${example}/sdkconfig.defaults
-done
-
-cp -r $IDF_PATH/components/tcp_transport ${esp_mqtt_path}/..
-rm    ${esp_mqtt_path}/../tcp_transport/transport_ssl.c
-echo -e "#include \"esp_transport.h\"\nvoid esp_transport_ws_set_path(esp_transport_handle_t t, const char *path) {}" > ${esp_mqtt_path}/../tcp_transport/transport_ws.c
-
-cp $IDF_PATH/components/mqtt/Kconfig  ${esp_mqtt_path}
-sed 's/esp-mqtt/\./g' $IDF_PATH/components/mqtt/component.mk  > ${esp_mqtt_path}/component.mk
-git checkout $former_commit_id
-popd
--- a/ci/publish_connect_mqtt_qemu.yml
+++ b/ci/publish_connect_mqtt_qemu.yml
@@ -1,7 +0,0 @@
-CaseConfig:
- name: test_app_protocol_mqtt_publish_connect
-  overwrite:
-    dut:
-      class: ESP32QEMUDUT
-      package: ttfw_idf
-
--- a/ci/set_idf.sh
+++ b/ci/set_idf.sh
@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-
-# sets up the IDF repo incl submodules with specified version as $1
-set -o errexit # Exit if command failed.
-
-if [ -z $IDF_PATH ] || [ -z $MQTT_PATH ] || [ -z $1 ] ; then
-    echo "Mandatory variables undefined"
-    exit 1;
-fi;
-
-echo "Checking out IDF version $1"
-cd $IDF_PATH
-# Cleans out the untracked files in the repo, so the next "git checkout" doesn't fail
-git clean -f
-git checkout $1
-# Removes the mqtt submodule, so the next submodule update doesn't fail
-rm -rf $IDF_PATH/components/mqtt/esp-mqtt
-git submodule update --init --recursive
-
--- a/ci/set_mqtt.sh
+++ b/ci/set_mqtt.sh
@@ -1,16 +0,0 @@
-#!/usr/bin/env bash
-
-# sets the mqtt in IDF tree as a submodule with the version specified as $1
-set -o errexit # Exit if command failed.
-
-if [ -z $IDF_PATH ] || [ -z $MQTT_PATH ] || [ -z $1 ] ; then
-    echo "Mandatory variables undefined"
-    exit 1;
-fi;
-
-echo "Checking out MQTT version to $1"
-# exchange remotes of mqtt submodules with plain copy
-cd $IDF_PATH/components/mqtt/esp-mqtt
-rm -rf .git                # removes the actual IDF referenced version
-cp -r $MQTT_PATH/.git .    # replaces with the MQTT_PATH (CI checked tree)
-git reset --hard $1        # sets the requested version
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -0,0 +1,57 @@
+# This is Doxygen configuration file
+#
+# Doxygen provides over 260 configuration statements
+# To make this file easier to follow,
+# it contains only statements that are non-default
+#
+# NOTE:
+# It is recommended not to change defaults unless specifically required
+# Test any changes how they affect generated documentation
+# Make sure that correct warnings are generated to flag issues with documented code
+#
+# For the complete list of configuration statements see:
+# http://doxygen.nl/manual/config.html
+
+
+PROJECT_NAME = "ESP-MQTT Programming Guide"
+
+## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
+## to automatically generate API reference list files heder_file.inc
+## These files are placed in '_inc' directory
+## and used to include in API reference documentation
+
+INPUT = \
+    $(PROJECT_PATH)/include/mqtt_client.h \
+    $(PROJECT_PATH)/include/mqtt5_client.h \
+    $(PROJECT_PATH)/include/mqtt_supported_features.h
+
+## Get warnings for functions that have no documentation for their parameters or return value
+##
+WARN_NO_PARAMDOC = YES
+
+## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
+##
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = \
+    $(ENV_DOXYGEN_DEFINES) \
+
+## Do not complain about not having dot
+##
+HAVE_DOT = NO
+
+## Generate XML that is required for Breathe
+##
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
+
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+GENERATE_MAN    = YES
+GENERATE_RTF    = NO
+
+## Skip distracting progress messages
+##
+QUIET = YES
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+#
+# Common (non-language-specific) configuration for Sphinx
+#
+
+# type: ignore
+# pylint: disable=wildcard-import
+# pylint: disable=undefined-variable
+
+from __future__ import print_function, unicode_literals
+
+from esp_docs.conf_docs import *  # noqa: F403,F401
+
+# IDF_PATH validation removed - not needed for standalone component docs
+# Only required when using ESP-IDF extensions that depend on IDF environment
+
+
+extensions += ['sphinx_copybutton',
+               # Needed as a trigger for running doxygen
+               'esp_docs.esp_extensions.dummy_build_system',
+               'esp_docs.esp_extensions.run_doxygen'
+               ]
+
+# link roles config
+github_repo = 'espressif/esp-mqtt'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esp-mqtt'
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-mqtt'
+versions_url = './_static/mqtt_docs_versions.js'
+
+idf_targets = [ 'esp32' ]
+languages = ['en']
+
+
+
--- a/docs/doxygen-known-warnings.txt
+++ b/docs/doxygen-known-warnings.txt
@@ -0,0 +1,2 @@
+# Known doxygen warnings for ESP-MQTT documentation build
+# Currently no known doxygen warnings expected
--- a/docs/en/conf.py
+++ b/docs/en/conf.py
@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+import datetime
+
+current_year = datetime.datetime.now().year
+
+# General information about the project.
+project = u'ESP-MQTT Programming Guide'
+copyright = u'2019 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(current_year)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -21,23 +21,23 @@ Features
 Application Examples
 --------------------

-   - :example:`protocols/mqtt/tcp` demonstrates how to implement MQTT communication over TCP (default port 1883).
+   - :example:`tcp` demonstrates how to implement MQTT communication over TCP (default port 1883).

-   - :example:`protocols/mqtt/ssl` demonstrates how to use SSL transport to implement MQTT communication over TLS (default port 8883).
+   - :example:`ssl` demonstrates how to use SSL transport to implement MQTT communication over TLS (default port 8883).

-   - :example:`protocols/mqtt/ssl_ds` demonstrates how to use digital signature peripheral for authentication to implement MQTT communication over TLS (default port 8883).
+   - :example:`ssl_ds` demonstrates how to use digital signature peripheral for authentication to implement MQTT communication over TLS (default port 8883).

-   - :example:`protocols/mqtt/ssl_mutual_auth` demonstrates how to use certificates for authentication to implement MQTT communication (default port 8883).
+   - :example:`ssl_mutual_auth` demonstrates how to use certificates for authentication to implement MQTT communication (default port 8883).

-   - :example:`protocols/mqtt/ssl_psk` demonstrates how to use pre-shared keys for authentication to implement MQTT communication over TLS (default port 8883).
+   - :example:`ssl_psk` demonstrates how to use pre-shared keys for authentication to implement MQTT communication over TLS (default port 8883).

-   - :example:`protocols/mqtt/ws` demonstrates how to implement MQTT communication over WebSocket (default port 80).
+   - :example:`ws` demonstrates how to implement MQTT communication over WebSocket (default port 80).

-   - :example:`protocols/mqtt/wss` demonstrates how to implement MQTT communication over WebSocket Secure (default port 443).
+   - :example:`wss` demonstrates how to implement MQTT communication over WebSocket Secure (default port 443).

-   - :example:`protocols/mqtt5` demonstrates how to use ESP-MQTT library to connect to broker with MQTT v5.0.
+   - :example:`mqtt5` demonstrates how to use ESP-MQTT library to connect to broker with MQTT v5.0.

-   - :example:`protocols/mqtt/custom_outbox` demonstrates how to customize the outbox in the ESP-MQTT library.
+   - :example:`custom_outbox` demonstrates how to customize the outbox in the ESP-MQTT library.

 MQTT Message Retransmission
 ---------------------------
@@ -124,7 +124,7 @@ The broker certificate may be set in PEM or DER format. To select DER, the equiv
       openssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 < /dev/null \
       2> /dev/null | openssl x509 -outform PEM > mqtt_eclipse_org.pem

-  Check the sample application: :example:`protocols/mqtt/ssl`
+-  Check the sample application: :example:`ssl`
 -  Configuration:

 .. code:: c
--- a/docs/sphinx-known-warnings.txt
+++ b/docs/sphinx-known-warnings.txt
@@ -0,0 +1,37 @@
+mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:type:: struct esp_mqtt_event_t esp_mqtt_event_t'.[39;49;00m
+mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:type:: struct esp_mqtt_client_config_t esp_mqtt_client_config_t'.[39;49;00m
+mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enum:: esp_mqtt_event_id_t'.[39;49;00m
+mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enum:: esp_mqtt_connect_return_code_t'.[39;49;00m
+mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enum:: esp_mqtt_error_type_t'.[39;49;00m
+mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enum:: esp_mqtt_transport_t'.[39;49;00m
+mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enum:: esp_mqtt_protocol_ver_t'.[39;49;00m
+mqtt5_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enumerator:: __attribute__'.[39;49;00m
+index.rst:line: CRITICAL: Duplicate ID: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".
+index.rst:line: WARNING: Duplicate explicit target name: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".[39;49;00m
+mqtt5_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enumerator:: __attribute__'.[39;49;00m
+index.rst:line: CRITICAL: Duplicate ID: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".
+index.rst:line: WARNING: Duplicate explicit target name: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".[39;49;00m
+mqtt5_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enumerator:: __attribute__'.[39;49;00m
+index.rst:line: CRITICAL: Duplicate ID: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".
+index.rst:line: WARNING: Duplicate explicit target name: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".[39;49;00m
+mqtt5_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enumerator:: __attribute__'.[39;49;00m
+index.rst:line: CRITICAL: Duplicate ID: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".
+index.rst:line: WARNING: Duplicate explicit target name: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".[39;49;00m
+index.rst:line: WARNING: undefined label: 'config_mqtt_outbox_expired_timeout_ms'[39;49;00m
+index.rst:line: WARNING: undefined label: 'config_mqtt_report_deleted_messages'[39;49;00m
+index.rst:line: WARNING: undefined label: 'esp_tls_server_verification'[39;49;00m
+index.rst:line: WARNING: undefined label: 'config_mqtt_protocol_311'[39;49;00m
+index.rst:line: WARNING: undefined label: 'config_mqtt_transport_ssl'[39;49;00m
+index.rst:line: WARNING: undefined label: 'config_mqtt_transport_websocket'[39;49;00m
+index.rst:line: WARNING: undefined label: 'config_mqtt_custom_outbox'[39;49;00m
--- a/docs/zh_CN/conf.py
+++ b/docs/zh_CN/conf.py
@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+import datetime
+
+current_year = datetime.datetime.now().year
+
+# General information about the project.
+project = u'ESP-MQTT Programming Guide'
+copyright = u'2019 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(current_year)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'zh_CN'
--- a/docs/zh_CN/index.rst
+++ b/docs/zh_CN/index.rst
@@ -21,23 +21,23 @@ ESP-MQTT 是 `MQTT <https://mqtt.org/>`__ 协议客户端的实现，MQTT 是一
 应用示例
 -------------------

-   - :example:`protocols/mqtt/tcp` 演示了如何通过 TCP 实现 MQTT 通信（默认端口 1883）。
+   - :example:`tcp` 演示了如何通过 TCP 实现 MQTT 通信（默认端口 1883）。

-   - :example:`protocols/mqtt/ssl` 演示了如何使用 SSL 传输来实现基于 TLS 的 MQTT 通信（默认端口 8883）。
+   - :example:`ssl` 演示了如何使用 SSL 传输来实现基于 TLS 的 MQTT 通信（默认端口 8883）。

-   - :example:`protocols/mqtt/ssl_ds` 演示了如何使用数字签名外设进行身份验证，以实现基于 TLS 的 MQTT 通信（默认端口 8883）。
+   - :example:`ssl_ds` 演示了如何使用数字签名外设进行身份验证，以实现基于 TLS 的 MQTT 通信（默认端口 8883）。

-   - :example:`protocols/mqtt/ssl_mutual_auth` 演示了如何使用证书进行身份验证实现 MQTT 通信（默认端口 8883）。
+   - :example:`ssl_mutual_auth` 演示了如何使用证书进行身份验证实现 MQTT 通信（默认端口 8883）。

-   - :example:`protocols/mqtt/ssl_psk` 演示了如何使用预共享密钥进行身份验证，以实现基于 TLS 的 MQTT 通信（默认端口 8883）。
+   - :example:`ssl_psk` 演示了如何使用预共享密钥进行身份验证，以实现基于 TLS 的 MQTT 通信（默认端口 8883）。

-   - :example:`protocols/mqtt/ws` 演示了如何通过 WebSocket 实现 MQTT 通信（默认端口 80）。
+   - :example:`ws` 演示了如何通过 WebSocket 实现 MQTT 通信（默认端口 80）。

-   - :example:`protocols/mqtt/wss` 演示了如何通过 WebSocket Secure 实现 MQTT 通信（默认端口 443）。
+   - :example:`wss` 演示了如何通过 WebSocket Secure 实现 MQTT 通信（默认端口 443）。

-   - :example:`protocols/mqtt5` 演示了如何使用 ESP-MQTT 库通过 MQTT v5.0 连接到代理。
+   - :example:`mqtt5` 演示了如何使用 ESP-MQTT 库通过 MQTT v5.0 连接到代理。

-   - :example:`protocols/mqtt/custom_outbox` 演示了如何自定义 ESP-MQTT 库中的 outbox。
+   - :example:`custom_outbox` 演示了如何自定义 ESP-MQTT 库中的 outbox。

 MQTT 消息重传
 --------------------------
@@ -124,7 +124,7 @@ ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避
       openssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 < /dev/null \
       2> /dev/null | openssl x509 -outform PEM > mqtt_eclipse_org.pem

-  检查示例应用程序：:example:`protocols/mqtt/ssl`
+-  检查示例应用程序：:example:`ssl`
 -  配置：

 .. code:: c