remove necessary configuration files to build documentation

.gitlab-ci.yml

@@ -3,23 +3,15 @@ stages:
   - deploy
   - deploy_docs
 
-# global variables
-variables: &global-variables
-  ESP_DOCS_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.0:2-2"
-  IDF_PATH: "$CI_PROJECT_DIR/esp-idf"
+
+
+variables:
+  # Versioned esp-idf-doc env image to use for all document building jobs
+  ESP_DOCS_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.0"
+  ESP_SR_PATH: "$CI_PROJECT_DIR"
+  IDF_PATH: $CI_PROJECT_DIR/esp-idf
   IDF_REPO: ${GITLAB_SSH_SERVER}/espressif/esp-idf.git
-  GIT_STRATEGY: clone
-  GIT_SUBMODULE_STRATEGY: recursive
-  ESPCI_TOKEN: $GITLAB_KEY
 
-before_script:
-  - echo $ESP_DOCS_ENV_IMAGE
-
-default:
-  retry:
-    max: 2
-    # In case of a runner failure we could hop to another one, or a network error could go away.
-    when: always
 
 .setup_idf_ci_env: &setup_idf_ci_env
   - source esp-idf/tools/ci/utils.sh
@@ -27,99 +19,64 @@ default:
   - esp-idf/tools/idf_tools.py install
   - esp-idf/tools/idf_tools.py export
 
-doc_build_html_en:
+.build_template:
   stage: build
   image: $ESP_DOCS_ENV_IMAGE
-  tags:
-    - build_docs
-  needs: []
-  artifacts:
-    when: always
-    paths:
-      - docs/_build/*/*/*.txt
-      - docs/_build/*/*/html/*
-    expire_in: 6 mos
-  script:
-    - cd docs
-    - ./check_lang_folder_sync.sh
-    - ./check_doc_chars.py
-    - pip install -r requirements.txt
-    # build html
-    - build-docs -t esp32 -l en -bs html
 
-doc_build_html_cn:
-  stage: build
-  image: $ESP_DOCS_ENV_IMAGE
-  tags:
-    - build_docs
-  needs: []
+build_esp_sr_html:
+  extends:
+    - .build_template
+  variables:
+    DOCS_DIR: $CI_PROJECT_DIR/docs
   artifacts:
     when: always
     paths:
-      - docs/_build/*/*/*.txt
-      - docs/_build/*/*/html/*
-    expire_in: 6 mos
+      - $DOCS_DIR/_build/*/*/html/*
+      - $DOCS_DIR/_build/*/*/*.txt
+    expire_in: 4 days
   script:
-    - cd docs
+    - cd $DOCS_DIR
     - ./check_lang_folder_sync.sh
     - ./check_doc_chars.py
-    - pip install -r requirements.txt
-    # build html
-    - build-docs -t esp32 -l zh_CN -bs html
+    - build-docs --skip-reqs-check -l $DOCLANG -t $DOCTGT
+    - echo "ESP-SR documentation preview available at $CI_JOB_URL/artifacts/file/docs/_build/$DOCLANG/$DOCTGT/html/index.html"
+  parallel:
+    matrix:
+      - DOCLANG: ["en", "zh_CN"]
+        DOCTGT: ["esp32", "esp32s3"]
 
-# Separate PDF build and HTML build due to artifacts size limit.
-doc_build_pdf_en:
-  stage: build
-  image: $ESP_DOCS_ENV_IMAGE
-  tags:
-    - build_docs
-  needs: []
+build_esp_sr_pdf:
+  extends:
+    - .build_template
+  variables:
+    DOCS_DIR: $CI_PROJECT_DIR/docs
   artifacts:
     when: always
     paths:
-      - docs/_build/*/*/*.txt
-      - docs/_build/*/*/latex/*
-    expire_in: 6 mos
+      - $DOCS_DIR/_build/*/*/latex/*
+      - $DOCS_DIR/_build/*/*/*.txt
+    expire_in: 4 days
   script:
-    - cd docs
+    - cd $DOCS_DIR
     - ./check_lang_folder_sync.sh
     - ./check_doc_chars.py
-    - pip install -r requirements.txt
-    # build pdf
-    - build-docs -t esp32 -l en -bs latex
+    - build-docs --skip-reqs-check -l $DOCLANG -t $DOCTGT
+  parallel:
+    matrix:
+      - DOCLANG: ["en", "zh_CN"]
+        DOCTGT: ["esp32", "esp32s3"]
 
-doc_build_pdf_cn:
-  stage: build
-  image: $ESP_DOCS_ENV_IMAGE
-  tags:
-    - build_docs
-  needs: []
-  artifacts:
-    when: always
-    paths:
-      - docs/_build/*/*/*.txt
-      - docs/_build/*/*/latex/*
-    expire_in: 6 mos
-  script:
-    - cd docs
-    - ./check_lang_folder_sync.sh
-    - ./check_doc_chars.py
-    - pip install -r requirements.txt
-    # build pdf
-    - build-docs -t esp32 -l zh_CN -bs latex
 
 .deploy_docs_template:
   stage: deploy_docs
   image: $ESP_DOCS_ENV_IMAGE
   tags:
-    - deploy
+    - deploy_docs
   needs:
-    - doc_build_html_en
-    - doc_build_html_cn
-    - doc_build_pdf_en
-    - doc_build_pdf_cn
+    - build_esp_sr_html
+    - build_esp_sr_pdf
   script:
-    - source ${CI_PROJECT_DIR}/docs/utils.sh
+    - source ${CI_PROJECT_DIR}/ci/utils.sh
     - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
     - export GIT_VER=$(git describe --always)
     - pip install -r ${CI_PROJECT_DIR}/docs/requirements.txt
@@ -177,4 +134,4 @@ push_to_github:
     - echo -e "Host github.com\n\tStrictHostKeyChecking no\n" >> ~/.ssh/config
     - git remote remove github &>/dev/null || true
     - git remote add github git@github.com:espressif/esp-sr.git
-    - git push github "${CI_COMMIT_SHA}:refs/heads/${CI_COMMIT_REF_NAME}"
+    - git push github "${CI_COMMIT_SHA}:refs/heads/${CI_COMMIT_REF_NAME}"

.readthedocs.yml

@@ -1,18 +0,0 @@
-# .readthedocs.yml
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-# Required
-version: 2
-
-# Optionally build your docs in additional formats such as PDF and ePub
-formats:
-  - htmlzip
-  - pdf
-
-# Optionally set the version of Python and requirements required to build your docs
-python:
-  version: 3.7
-  install:
-    - requirements: docs/setuptools.requirements.txt
-    - requirements: docs/requirements.txt

ci/utils.sh

@@ -1,4 +1,4 @@
-# Bash helper functions for adding SSH keys
+# Modified from https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/utils.sh
 
 function add_ssh_keys() {
   local key_string="${1}"
@@ -15,4 +15,4 @@ function add_doc_server_ssh_keys() {
   local server_user="${3}"
   add_ssh_keys "${key_string}"
   echo -e "Host ${server_url}\n\tStrictHostKeyChecking no\n\tUser ${server_user}\n" >>~/.ssh/config
-}
+}

docs/Doxyfile

@@ -1,70 +0,0 @@
-# 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-SR User 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)/src/include/esp_mn_speech_commands.h
-##    $(PROJECT_PATH)/components/at/include/esp_at.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             = \
-    __attribute__(x)= \
-    IDF_DEPRECATED(X)= \
-    IRAM_ATTR= \
-    configSUPPORT_DYNAMIC_ALLOCATION=1 \
-    configSUPPORT_STATIC_ALLOCATION=1 \
-    configQUEUE_REGISTRY_SIZE=1 \
-    configUSE_RECURSIVE_MUTEXES=1 \
-    configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS=1 \
-    configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \
-    configUSE_APPLICATION_TASK_TAG=1 \
-    configTASKLIST_INCLUDE_COREID=1
-
-## 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
-## Log warnings in a file for further review
-##
-WARN_LOGFILE = "doxygen-warning-log.txt"
-

docs/_static/docs_version.js

@@ -0,0 +1,12 @@
+var DOCUMENTATION_VERSIONS = {
+  DEFAULTS: { has_targets: false,
+              supported_targets: [ "esp32" ]
+            },
+  VERSIONS: [
+    { name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32s3" ] },
+  ],
+  IDF_TARGETS: [
+     { text: "ESP32", value: "esp32"},
+     { text: "ESP32-S3", value: "esp32s3"},
+  ]
+};

docs/_static/js/at_versions.js

@@ -1,32 +0,0 @@
-var DOCUMENTATION_VERSIONS = {
-    DEFAULTS: { has_targets: false,
-                supported_targets: [ "esp32s3" ]
-              },
-    VERSIONS: [
-        // latest
-        { name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32c2", "esp32c3" ] },
-
-        // v2.4.0.0
-        { name: "release-v2.4.0.0", has_targets: true, supported_targets: [ "esp32", "esp32c3" ]},
-
-        // v2.3.0.0
-        { name: "release-v2.3.0.0_esp32c3", has_targets: false, supported_targets: [ "esp32c3" ]},
-
-        // v2.2.0.0
-        { name: "release-v2.2.0.0_esp32c3", has_targets: false, supported_targets: [ "esp32c3" ]},
-        { name: "release-v2.2.0.0_esp32", has_targets: false, supported_targets: [ "esp32", "esp32s2" ]},
-        { name: "release-v2.2.0.0_esp8266", has_targets: false, supported_targets: [ "esp8266" ]},
-
-        // v2.1.0.0
-        { name: "release-v2.1.0.0_esp32", has_targets: false, supported_targets: [ "esp32" ]},
-        { name: "release-v2.1.0.0_esp8266", has_targets: false, supported_targets: [ "esp8266" ]},
-        { name: "release-v2.1.0.0_esp32s2", has_targets: false, supported_targets: [ "esp32s2" ]},
-    ],
-    IDF_TARGETS: [
-       { text: "ESP32-C2 (ESP8684)", value: "esp32c2"},
-       { text: "ESP32-C3", value: "esp32c3"},
-       { text: "ESP32", value: "esp32"},
-       { text: "ESP8266", value: "esp8266"},
-       { text: "ESP32-S2", value: "esp32s2"},
-    ]
-};

docs/conf_common.py

@@ -1,45 +1,10 @@
-# -*- coding: utf-8 -*-
-#
-# Common (non-language-specific) configuration for Sphinx
-#
-# This file is imported from a language-specific conf.py (ie en/conf.py or
-# zh_CN/conf.py)
+from esp_docs.conf_docs import *  # noqa: F403,F401
 
-from __future__ import print_function, unicode_literals
-
-import os.path
-
-#ESP_DOCS_PATH = os.environ['ESP_DOCS_PATH']
-
-try:
-    from esp_docs.conf_docs import *  # noqa: F403,F401
-except ImportError:
-    import os
-    import sys
-    sys.path.insert(0, os.path.abspath(ESP_DOCS_PATH))
-    from conf_docs import *  # noqa: F403,F401
-
-ESP32_DOCS = ['audio_front_end/README.rst',
-              'wake_word_engine/README.rst',
-              'wake_word_engine/ESP_Wake_Words_Customization.rst',
-              'speech_command_recognition/README.rst',
-              'flash_model/README.rst',
-              'audio_front_end/Espressif_Microphone_Design_Guidelines.rst',
-              'test_report/README.rst',
-              'benchmark/README.rst',
-            ]
-
-# format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
-conditional_include_dict = {
-                            'esp32':ESP32_DOCS,
-                            }
+languages = ['en', 'zh_CN']
+idf_targets = ['esp32', 'esp32s3']
 
 extensions += ['sphinx_copybutton',
-               # Note: order is important here, events must
-               # be registered by one extension before they can be
-               # connected to another extension
-               'esp_docs.esp_extensions.dummy_build_system',
-               'esp_docs.esp_extensions.run_doxygen',
+               'sphinxcontrib.wavedrom',
                ]
 
 # link roles config
@@ -49,19 +14,14 @@ github_repo = 'espressif/esp-sr'
 html_context['github_user'] = 'espressif'
 html_context['github_repo'] = 'esp-sr'
 
-idf_targets = ['esp32', 'esp32s2', 'esp32s3']
-languages = ['en', 'zh_CN']
-
-google_analytics_id = os.environ.get('CI_GOOGLE_ANALYTICS_ID', None)
-
-project_homepage = 'https://github.com/espressif/esp-sr'
-
 html_static_path = ['../_static']
 
 # Extra options required by sphinx_idf_theme
 project_slug = 'esp-sr'
 
-versions_url = './_static/js/at_versions.js'
+# Contains info used for constructing target and version selector
+# Can also be hosted externally, see esp-idf for example
+versions_url = '_static/docs_version.js'
 
 # Final PDF filename will contains target and version
-pdf_file_prefix = u'esp-sr'
+pdf_file_prefix = u'esp-sr'

docs/doxygen-known-warnings.txt

@@ -1 +0,0 @@
-semphr.h:line: warning: argument 'pxStaticSemaphore' of command @param is not found in the argument list of xSemaphoreCreateCounting(uxMaxCount, uxInitialCount)

docs/en/conf.py

@@ -6,19 +6,20 @@
 
 # Importing conf_common adds all the non-language-specific
 # parts to this conf module
-import sys
-import os
-sys.path.insert(0, os.path.abspath('..'))
-from conf_common import *  # noqa: F401, F403 - need to make available everything from common
+
+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
 
 # General information about the project.
-project = u'ESP-SR User Guide'
-copyright = u'2016 - 2022, Espressif Systems (Shanghai) Co., Ltd.'
-
+project = u'ESP-SR'
+copyright = u'2016 - 2022, Espressif Systems (Shanghai) Co., Ltd'
 pdf_title = u'ESP-SR User Guide'
-# Final PDF filename will contains target and version
-pdf_file_prefix = u'esp-sr'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-language = 'en'
+language = 'en'

docs/zh_CN/conf.py

@@ -6,19 +6,21 @@
 
 # Importing conf_common adds all the non-language-specific
 # parts to this conf module
-import sys
-import os
-sys.path.insert(0, os.path.abspath('..'))
-from conf_common import *  # noqa: F401, F403 - need to make available everything from common
+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
 
 # General information about the project.
-project = u'ESP-SR 用户指南'
+project = u'ESP-SR'
 copyright = u'2016 - 2022 乐鑫信息科技（上海）股份有限公司'
-
-pdf_title = u'ESP-SR 用户指南'
+pdf_title = u'ESP-SR 用户手册'
 # Final PDF filename will contains target and version
 pdf_file_prefix = u'esp-sr'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-language = 'zh_CN'
+language = 'zh_CN'