diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index f4b3c67..2bdac2e 100644 --- a/.gitlab-ci.yml +++ b/.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}" \ No newline at end of file + - git push github "${CI_COMMIT_SHA}:refs/heads/${CI_COMMIT_REF_NAME}" diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index 4179f6c..0000000 --- a/.readthedocs.yml +++ /dev/null @@ -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 \ No newline at end of file diff --git a/docs/utils.sh b/ci/utils.sh old mode 100755 new mode 100644 similarity index 85% rename from docs/utils.sh rename to ci/utils.sh index 84f3748..d963862 --- a/docs/utils.sh +++ b/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 -} +} \ No newline at end of file diff --git a/docs/Doxyfile b/docs/Doxyfile deleted file mode 100755 index df6dc25..0000000 --- a/docs/Doxyfile +++ /dev/null @@ -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" - diff --git a/docs/_static/docs_version.js b/docs/_static/docs_version.js new file mode 100644 index 0000000..bc58e87 --- /dev/null +++ b/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"}, + ] +}; diff --git a/docs/_static/js/at_versions.js b/docs/_static/js/at_versions.js deleted file mode 100644 index f9fe043..0000000 --- a/docs/_static/js/at_versions.js +++ /dev/null @@ -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"}, - ] -}; diff --git a/docs/conf_common.py b/docs/conf_common.py index 5e1b71f..8dd10fa 100755 --- a/docs/conf_common.py +++ b/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' \ No newline at end of file diff --git a/docs/doxygen-known-warnings.txt b/docs/doxygen-known-warnings.txt deleted file mode 100644 index a2fd101..0000000 --- a/docs/doxygen-known-warnings.txt +++ /dev/null @@ -1 +0,0 @@ -semphr.h:line: warning: argument 'pxStaticSemaphore' of command @param is not found in the argument list of xSemaphoreCreateCounting(uxMaxCount, uxInitialCount) diff --git a/docs/en/conf.py b/docs/en/conf.py index c41fb67..6aa2273 100755 --- a/docs/en/conf.py +++ b/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' \ No newline at end of file diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index aa2a47a..6cc5a3d 100755 --- a/docs/zh_CN/conf.py +++ b/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' \ No newline at end of file