From 5aa15899721dd9c5efd424cb6dcc05bfb8bc2466 Mon Sep 17 00:00:00 2001 From: Gao Wei Date: Thu, 5 Sep 2024 17:42:25 +0800 Subject: [PATCH] docs: Migrate esp-adf docs to esp-docs --- .gitlab-ci.yml | 2 +- .gitlab/ci/docs.yml | 161 +++++- components/audio_hal/driver/es8374/es8374.h | 498 +++++++++--------- components/audio_hal/driver/es8388/es8388.h | 7 +- components/audio_sal/include/audio_mem.h | 16 +- .../led_bar/include/led_bar_is31x.h | 8 +- .../led_indicator/include/led_indicator.h | 8 +- .../ota_service/include/ota_proc_default.h | 38 +- docs/Doxyfile | 218 ++++---- docs/_static/docs_version.js | 14 + docs/conf_common.py | 107 ++-- .../api-reference/abstraction/audio_hal.rst | 2 +- docs/en/api-reference/abstraction/es8374.rst | 2 +- docs/en/api-reference/abstraction/es8388.rst | 2 +- docs/en/api-reference/abstraction/ringbuf.rst | 2 +- docs/en/api-reference/abstraction/zl38063.rst | 2 +- .../audio-processing/audio_sonic.rst | 2 +- .../audio-processing/downmix.rst | 2 +- .../audio-processing/equalizer.rst | 2 +- .../audio-processing/filter_resample.rst | 2 +- docs/en/api-reference/codecs/aac_decoder.rst | 2 +- docs/en/api-reference/codecs/amr_codecs.rst | 6 +- docs/en/api-reference/codecs/flac_decoder.rst | 2 +- docs/en/api-reference/codecs/mp3_decoder.rst | 2 +- docs/en/api-reference/codecs/ogg_decoder.rst | 2 +- docs/en/api-reference/codecs/opus_decoder.rst | 2 +- docs/en/api-reference/codecs/wav_codecs.rst | 4 +- .../api-reference/framework/audio_common.rst | 2 +- .../api-reference/framework/audio_element.rst | 2 +- .../framework/audio_event_iface.rst | 2 +- .../framework/audio_pipeline.rst | 2 +- docs/en/api-reference/framework/esp_audio.rst | 4 +- docs/en/api-reference/kconfig.rst | 2 +- .../peripherals/esp_peripherals.rst | 2 +- .../peripherals/periph_adc_button.rst | 2 +- .../peripherals/periph_button.rst | 2 +- .../peripherals/periph_console.rst | 2 +- .../peripherals/periph_is31fl3216.rst | 2 +- .../api-reference/peripherals/periph_led.rst | 2 +- .../peripherals/periph_sdcard.rst | 2 +- .../peripherals/periph_spiffs.rst | 2 +- .../peripherals/periph_touch.rst | 2 +- .../api-reference/peripherals/periph_wifi.rst | 2 +- docs/en/api-reference/playlist/index.rst | 12 +- .../services/battery_service.rst | 4 +- .../services/bluetooth_service.rst | 8 +- .../services/coredump_upload_service.rst | 2 +- .../services/display_service.rst | 10 +- .../api-reference/services/dueros_service.rst | 2 +- docs/en/api-reference/services/index.rst | 4 +- .../services/input_key_service.rst | 4 +- .../en/api-reference/services/ota_service.rst | 6 +- .../api-reference/services/wifi_service.rst | 12 +- .../speech-recognition/audio_recorder.rst | 6 +- docs/en/api-reference/streams/index.rst | 22 +- docs/en/conf.py | 6 +- docs/link-roles.py | 10 +- docs/requirements.txt | 17 +- docs/zh_CN/api-reference/playlist/index.rst | 12 +- .../services/battery_service.rst | 4 +- .../services/bluetooth_service.rst | 8 +- .../services/coredump_upload_service.rst | 2 +- .../services/display_service.rst | 10 +- .../api-reference/services/dueros_service.rst | 2 +- docs/zh_CN/api-reference/services/index.rst | 4 +- .../services/input_key_service.rst | 4 +- .../api-reference/services/ota_service.rst | 6 +- .../api-reference/services/wifi_service.rst | 12 +- docs/zh_CN/api-reference/streams/index.rst | 22 +- docs/zh_CN/conf.py | 6 +- tools/ci/utils.sh | 8 + 71 files changed, 714 insertions(+), 660 deletions(-) create mode 100644 docs/_static/docs_version.js diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index a99172885..a3e160ea9 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,9 +1,9 @@ stages: - pre_check - build - - assign_test - target_test - deploy + - post_deploy variables: # System environment diff --git a/.gitlab/ci/docs.yml b/.gitlab/ci/docs.yml index db3a464e4..f435f7273 100644 --- a/.gitlab/ci/docs.yml +++ b/.gitlab/ci/docs.yml @@ -26,6 +26,9 @@ .if-label-build_docs: &if-label-build_docs if: '$BOT_LABEL_BUILD_DOCS || $CI_MERGE_REQUEST_LABELS =~ /^(?:[^,\n\r]+,)*build_docs(?:,[^,\n\r]+)*$/i' +.if-label-docs_full: &if-label-docs_full + if: '$BOT_LABEL_DOCS_FULL || $CI_MERGE_REQUEST_LABELS =~ /^(?:[^,\n\r]+,)*docs_full(?:,[^,\n\r]+)*$/i' + .doc-rules:build:docs: rules: - <<: *if-protected @@ -34,39 +37,139 @@ when: never - <<: *if-label-build_docs -build_docs: +.doc-rules:deploy:docs_production: + rules: + - <<: *if-protected + +.before_script_install_requirements: stage: build - extends: - - .doc-rules:build:docs - image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:v7 + image: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.0:4-4" tags: - build_docs + variables: + DOCS_DIR: $CI_PROJECT_DIR/docs + IDF_VERSION_TAG: "v5.0" + IDF_TAG_FLAG: "true" + dependencies: [] + +.build_docs_html_template: + extends: + - .before_script_install_requirements + variables: + DOC_BUILDERS: "html" + script: + - pip install -r docs/requirements.txt + - cd $DOCS_DIR + - mkdir -p $ADF_PATH/docs/_build/${DOCLANG}/generic/inc + - build-docs -bs $DOC_BUILDERS -l $DOCLANG build + - ./check_lang_folder_sync.sh + - echo "ESP-ADF Guide preview available at $CI_JOB_URL/artifacts/file/docs/_build/$DOCLANG/generic/html/index.html" + +.build_docs_pdf_template: + extends: + - .before_script_install_requirements + script: + - pip install -r docs/requirements.txt + - cd $DOCS_DIR + - mkdir -p $ADF_PATH/docs/_build/${DOCLANG}/generic/inc + - build-docs --skip-reqs-check -l $DOCLANG -bs latex + +build_docs_html: + extends: + - .build_docs_html_template + - .doc-rules: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 + - $DOCS_DIR/_build/*/*/*.txt + - $DOCS_DIR/_build/*/*/html/* + expire_in: 4 days + parallel: + matrix: + - DOCLANG: "en" + - DOCLANG: "zh_CN" + +build_docs_pdf: + extends: + - .build_docs_pdf_template + - .doc-rules:build:docs + artifacts: + when: always + paths: + - $DOCS_DIR/_build/*/*/latex/* + - $DOCS_DIR/_build/*/*/*.txt + expire_in: 4 days + parallel: + matrix: + - DOCLANG: "en" + - DOCLANG: "zh_CN" + +.deploy_docs_template: + stage: test_deploy + image: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.0" + variables: + DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/" + PYTHONUNBUFFERED: 1 + tags: + - deploy + - shiny + needs: + - job: "build_docs_html" + artifacts: true + optional: true + - job: "build_docs_pdf" + artifacts: true + optional: true 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 $ADF_PATH/docs/requirements.txt - - cd docs - - ./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 + - source ${CI_PROJECT_DIR}/tools/ci/utils.sh + - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER + - export GIT_VER=$(git describe --always ${PIPELINE_COMMIT_SHA} --) + - deploy-docs + +# stage: test_deploy +.deploy_docs_preview: + extends: + - .deploy_docs_template + rules: + - <<: *if-merge_request_event + - <<: *if-open-merge-request + when: never + - <<: *if-dev-push + when: never + - <<: *if-label-build_docs + - <<: *if-label-docs_full + changes: *patterns-docs-preview + variables: + TYPE: "preview" + # older branches use DOCS_DEPLOY_KEY, DOCS_SERVER, DOCS_SERVER_USER, DOCS_PATH for preview server so we keep these names for 'preview' + DOCS_DEPLOY_PRIVATEKEY: "$DOCS_DEPLOY_KEY" + DOCS_DEPLOY_SERVER: "$DOCS_SERVER" + DOCS_DEPLOY_SERVER_USER: "$DOCS_SERVER_USER" + DOCS_DEPLOY_PATH: "$DOCS_PATH" + DOCS_DEPLOY_URL_BASE: "https://$DOCS_PREVIEW_SERVER_URL/docs/esp-adf" + +# stage: post_deploy +deploy_docs_production: + # The DOCS_PROD_* variables used by this job are "Protected" so these branches must all be marked "Protected" in Gitlab settings + extends: + - .deploy_docs_template + - .doc-rules:deploy:docs_production + stage: post_deploy + dependencies: # set dependencies to null to avoid missing artifacts issue + needs: # ensure runs after push_to_github succeeded + - job: "build_docs_html" + artifacts: true + optional: true + - job: "build_docs_pdf" + artifacts: true + optional: true + - job: push_to_github + artifacts: false + variables: + TYPE: "preview" + DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PROD_DEPLOY_KEY" + DOCS_DEPLOY_SERVER: "$DOCS_PROD_SERVER" + DOCS_DEPLOY_SERVER_USER: "$DOCS_PROD_SERVER_USER" + DOCS_DEPLOY_PATH: "$DOCS_PROD_PATH" + DOCS_DEPLOY_URL_BASE: "https://docs.espressif.com/projects/esp-adf" + DEPLOY_STABLE: 1 diff --git a/components/audio_hal/driver/es8374/es8374.h b/components/audio_hal/driver/es8374/es8374.h index d54cb3323..6fb3c994c 100755 --- a/components/audio_hal/driver/es8374/es8374.h +++ b/components/audio_hal/driver/es8374/es8374.h @@ -1,251 +1,247 @@ -/* - * ESPRESSIF MIT License - * - * Copyright (c) 2018 - * - * Permission is hereby granted for use on all ESPRESSIF SYSTEMS products, in which case, - * it is free of charge, to any person obtaining a copy of this software and associated - * documentation files (the "Software"), to deal in the Software without restriction, including - * without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, - * and/or sell copies of the Software, and to permit persons to whom the Software is furnished - * to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in all copies or - * substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS - * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR - * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER - * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * - */ - -#ifndef __ES8374_H__ -#define __ES8374_H__ - -#include "esp_types.h" -#include "audio_hal.h" -#include "esxxx_common.h" - -#ifdef __cplusplus -extern "C" { -#endif - -/* ES8374 address */ -#define ES8374_ADDR 0x20 // 0x22:CE=1;0x20:CE=0 - -/** - * @brief Initialize ES8374 codec chip - * - * @param cfg configuration of ES8374 - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_codec_init(audio_hal_codec_config_t *cfg); - -/** - * @brief Deinitialize ES8374 codec chip - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_codec_deinit(void); - -/** - * @brief Configure ES8374 I2S format - * - * @param mode: set ADC or DAC or both - * @param fmt: ES8374 I2S format - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_config_fmt(es_module_t mode, es_i2s_fmt_t fmt); - -/** - * @brief Configure I2S clock in MSATER mode - * - * @param cfg: set bits clock and WS clock - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_i2s_config_clock(es_i2s_clock_t cfg); - -/** - * @brief Configure ES8374 data sample bits - * - * @param mode: set ADC or DAC or both - * @param bit_per_sample: bit number of per sample - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_set_bits_per_sample(es_module_t mode, es_bits_length_t bit_per_sample); - -/** - * @brief Start ES8374 codec chip - * - * @param mode: set ADC or DAC or both - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_start(es_module_t mode); - -/** - * @brief Stop ES8374 codec chip - * - * @param mode: set ADC or DAC or both - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_stop(es_module_t mode); - -/** - * @brief Set voice volume - * - * @param volume: voice volume (0~100) - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_codec_set_voice_volume(int volume); - -/** - * @brief Get voice volume - * - * @param[out] *volume: voice volume (0~100) - * - * @return - * - ESP_OK - * - ESP_FAIL - */ -esp_err_t es8374_codec_get_voice_volume(int *volume); - -/** - * @brief Mute or unmute ES8374 DAC. Basically you can use this function to mute or unmute the output - * - * @param enable mute(1) or unmute(0) - * - * @return - * - ESP_FAIL Parameter error - * - ESP_OK Success - */ -esp_err_t es8374_set_voice_mute(bool enable); - -/** - * @brief Get ES8374 DAC mute status - * - * @return - * - ESP_FAIL - * - ESP_OK - */ -esp_err_t es8374_get_voice_mute(void); - -/** - * @brief Set ES8374 mic gain - * - * @param gain db of mic gain - * - * @return - * - ESP_FAIL Parameter error - * - ESP_OK Success - */ -esp_err_t es8374_set_mic_gain(es_mic_gain_t gain); - -/** - * @brief Set ES8374 ADC input mode - * - * @param input adc input mode - * - * @return - * - ESP_FAIL Parameter error - * - ESP_OK Success - */ -esp_err_t es8374_config_adc_input(es_adc_input_t input); - -/** - * @brief Set ES8374 DAC output mode - * - * @param output dac output mode - * - * @return - * - ESP_FAIL Parameter error - * - ESP_OK Success - */ -esp_err_t es8374_config_dac_output(es_dac_output_t output); - -/** - * @brief Write ES8374 register - * - * @param reg_add address of register - * @param data data of register - * - * @return - * - ESP_FAIL Parameter error - * - ESP_OK Success - */ -esp_err_t es8374_write_reg(uint8_t reg_add, uint8_t data); - -/** - * @brief Print all ES8374 registers - * - * @return - * - void - */ -void es8374_read_all(); - -/** - * @brief Configure ES8374 codec mode and I2S interface - * - * @param mode codec mode - * @param iface I2S config - * - * @return - * - ESP_FAIL Parameter error - * - ESP_OK Success - */ -esp_err_t es8374_codec_config_i2s(audio_hal_codec_mode_t mode, audio_hal_codec_i2s_iface_t *iface); - -/** - * @brief Control ES8374 codec chip - * - * @param mode codec mode - * @param ctrl_state start or stop decode or encode progress - * - * @return - * - ESP_FAIL Parameter error - * - ESP_OK Success - */ -esp_err_t es8374_codec_ctrl_state(audio_hal_codec_mode_t mode, audio_hal_ctrl_t ctrl_state); - -/** - * @brief Set ES8374 PA power - * - * @param enable true for enable PA power, false for disable PA power - * - * @return - * - ESP_ERR_INVALID_ARG - * - ESP_OK - */ -esp_err_t es8374_pa_power(bool enable); - -#ifdef __cplusplus -} -#endif - -#endif //__ES8374_H__ - +/* + * ESPRESSIF MIT License + * + * Copyright (c) 2018 + * + * Permission is hereby granted for use on all ESPRESSIF SYSTEMS products, in which case, + * it is free of charge, to any person obtaining a copy of this software and associated + * documentation files (the "Software"), to deal in the Software without restriction, including + * without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, + * and/or sell copies of the Software, and to permit persons to whom the Software is furnished + * to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all copies or + * substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS + * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR + * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER + * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + * + */ + +#ifndef __ES8374_H__ +#define __ES8374_H__ + +#include "esp_types.h" +#include "audio_hal.h" +#include "esxxx_common.h" + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/* ES8374 address */ +#define ES8374_ADDR 0x20 // 0x22:CE=1;0x20:CE=0 + +/** + * @brief Initialize ES8374 codec chip + * + * @param cfg configuration of ES8374 + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_codec_init(audio_hal_codec_config_t *cfg); + +/** + * @brief Deinitialize ES8374 codec chip + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_codec_deinit(void); + +/** + * @brief Configure ES8374 I2S format + * + * @param mode Set ADC or DAC or both + * @param fmt ES8374 I2S format + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_config_fmt(es_module_t mode, es_i2s_fmt_t fmt); + +/** + * @brief Configure I2S clock in MSATER mode + * + * @param cfg Set bits clock and WS clock + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_i2s_config_clock(es_i2s_clock_t cfg); + +/** + * @brief Configure ES8374 data sample bits + * + * @param mode Set ADC or DAC or both + * @param bit_per_sample Bit number of per sample + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_set_bits_per_sample(es_module_t mode, es_bits_length_t bit_per_sample); + +/** + * @brief Start ES8374 codec chip + * + * @param mode Set ADC or DAC or both + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_start(es_module_t mode); + +/** + * @brief Stop ES8374 codec chip + * + * @param mode Set ADC or DAC or both + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_stop(es_module_t mode); + +/** + * @brief Set voice volume + * + * @param volume Voice volume (0~100) + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_codec_set_voice_volume(int volume); + +/** + * @brief Get voice volume + * + * @param[out] *volume Voice volume (0~100) + * + * @return + * - ESP_OK + * - ESP_FAIL + */ +esp_err_t es8374_codec_get_voice_volume(int *volume); + +/** + * @brief Mute or unmute ES8374 DAC. Basically you can use this function to mute or unmute the output + * + * @param[in,out] enable Enable Mute(1) or Unmute(0) + * + * @return + * - ESP_FAIL Parameter error + * - ESP_OK Success + */ +esp_err_t es8374_set_voice_mute(bool enable); + +/** + * @brief Get ES8374 DAC mute status + * + * @return + * - ESP_FAIL + * - ESP_OK + */ +esp_err_t es8374_get_voice_mute(void); + +/** + * @brief Set ES8374 mic gain + * + * @param[in,out] gain gain db of mic gain + * + * @return + * - ESP_FAIL Parameter error + * - ESP_OK Success + */ +esp_err_t es8374_set_mic_gain(es_mic_gain_t gain); + +/** + * @brief Set ES8374 ADC input mode + * + * @param[in] input ADC input mode + * + * @return + * - ESP_FAIL Parameter error + * - ESP_OK Success + */ +esp_err_t es8374_config_adc_input(es_adc_input_t input); + +/** + * @brief Set ES8374 DAC output mode + * + * @param[in] output DAC output mode + * + * @return + * - ESP_FAIL Parameter error + * - ESP_OK Success + */ +esp_err_t es8374_config_dac_output(es_dac_output_t output); + +/** + * @brief Write ES8374 register + * + * @param reg_add Address of register + * @param data Data of register + * + * @return + * - ESP_FAIL Parameter error + * - ESP_OK Success + */ +esp_err_t es8374_write_reg(uint8_t reg_add, uint8_t data); + +/** + * @brief Print all ES8374 registers + */ +void es8374_read_all(void); + +/** + * @brief Configure ES8374 codec mode and I2S interface + * + * @param mode Codec mode + * @param iface I2S config + * + * @return + * - ESP_FAIL Parameter error + * - ESP_OK Success + */ +esp_err_t es8374_codec_config_i2s(audio_hal_codec_mode_t mode, audio_hal_codec_i2s_iface_t *iface); + +/** + * @brief Control ES8374 codec chip + * + * @param mode Codec mode + * @param ctrl_state Start or stop decode or encode progress + * + * @return + * - ESP_FAIL Parameter error + * - ESP_OK Success + */ +esp_err_t es8374_codec_ctrl_state(audio_hal_codec_mode_t mode, audio_hal_ctrl_t ctrl_state); + +/** + * @brief Set ES8374 PA power + * + * @param enable True for enable PA power, false for disable PA power + * + * @return + * - ESP_ERR_INVALID_ARG + * - ESP_OK + */ +esp_err_t es8374_pa_power(bool enable); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif //__ES8374_H__ diff --git a/components/audio_hal/driver/es8388/es8388.h b/components/audio_hal/driver/es8388/es8388.h index b57ae68f3..3015aad49 100755 --- a/components/audio_hal/driver/es8388/es8388.h +++ b/components/audio_hal/driver/es8388/es8388.h @@ -264,12 +264,9 @@ esp_err_t es8388_config_dac_output(es_dac_output_t output); esp_err_t es8388_write_reg(uint8_t reg_add, uint8_t data); /** - * @brief Print all ES8388 registers - * - * @return - * - void + * @brief Print all ES8388 registers */ -void es8388_read_all(); +void es8388_read_all(void); /** * @brief Configure ES8388 codec mode and I2S interface diff --git a/components/audio_sal/include/audio_mem.h b/components/audio_sal/include/audio_mem.h index ff154baf4..bc6d45dea 100644 --- a/components/audio_sal/include/audio_mem.h +++ b/components/audio_sal/include/audio_mem.h @@ -56,12 +56,9 @@ void *audio_malloc(size_t size); void *audio_malloc_align(size_t alignment, size_t size); /** - * @brief Free memory in ADF + * @brief Free memory in ADF * * @param[in] ptr memory pointer - * - * @return - * - void */ void audio_free(void *ptr); @@ -90,14 +87,11 @@ void *audio_calloc(size_t nmemb, size_t size); void *audio_calloc_inner(size_t nmemb, size_t size); /** - * @brief Print heap memory status + * @brief Print heap memory status * - * @param[in] tag tag of log - * @param[in] line line of log - * @param[in] func function name of log - * - * @return - * - void + * @param[in] tag tag of log + * @param[in] line line of log + * @param[in] func function name of log */ void audio_mem_print(const char *tag, int line, const char *func); diff --git a/components/display_service/led_bar/include/led_bar_is31x.h b/components/display_service/led_bar/include/led_bar_is31x.h index e3262f4df..afd60c1f2 100644 --- a/components/display_service/led_bar/include/led_bar_is31x.h +++ b/components/display_service/led_bar/include/led_bar_is31x.h @@ -55,13 +55,9 @@ esp_periph_handle_t led_bar_is31x_init(); esp_err_t led_bar_is31x_pattern(void *handle, int pat, int value); /** - * @brief Destroy esp_periph_handle_t instance + * @brief Destroy esp_periph_handle_t instance * - * @param handle led bar instance - * - * @return - * - ESP_OK - * - ESP_FAIL + * @param handle led bar instance */ void led_bar_is31x_deinit(esp_periph_handle_t handle); diff --git a/components/display_service/led_indicator/include/led_indicator.h b/components/display_service/led_indicator/include/led_indicator.h index a356c8c42..6d6b92107 100644 --- a/components/display_service/led_indicator/include/led_indicator.h +++ b/components/display_service/led_indicator/include/led_indicator.h @@ -58,13 +58,9 @@ led_indicator_handle_t led_indicator_init(gpio_num_t num); esp_err_t led_indicator_pattern(void *handle, int pat, int value); /** - * @brief Destroy led_indicator_handle_t instance + * @brief Destroy led_indicator_handle_t instance * - * @param handle led indicator instance - * - * @return - * - ESP_OK - * - ESP_FAIL + * @param handle led indicator instance */ void led_indicator_deinit(led_indicator_handle_t handle); diff --git a/components/ota_service/include/ota_proc_default.h b/components/ota_service/include/ota_proc_default.h index 7e74e032f..249798d96 100644 --- a/components/ota_service/include/ota_proc_default.h +++ b/components/ota_service/include/ota_proc_default.h @@ -36,23 +36,17 @@ extern "C" { #endif /** - * @brief get the default process of `app partition` upgrade - * - * @param[in] ops pointer to `ota_upgrade_ops_t` structure - * - * @return - * - void - */ + * @brief get the default process of `app partition` upgrade + * + * @param[in] ops pointer to `ota_upgrade_ops_t` structure + */ void ota_app_get_default_proc(ota_upgrade_ops_t *ops); /** - * @brief get the default process of `data partition` upgrade - * - * @param[in] ops pointer to `ota_upgrade_ops_t` structure - * - * @return - * - void - */ + * @brief get the default process of `data partition` upgrade + * + * @param[in] ops pointer to `ota_upgrade_ops_t` structure + */ void ota_data_get_default_proc(ota_upgrade_ops_t *ops); /** @@ -82,15 +76,11 @@ ota_service_err_reason_t ota_data_image_stream_read(void *handle, char *buf, int ota_service_err_reason_t ota_data_partition_write(void *handle, char *buf, int size); /** - * @brief Indicates that the ota partition has been erased - * By default, this part of flash will be erased during ota. If the behavior of erasing is called in applition, this API needs to be called - * - * @param[in] handle pointer to upgrade handle - - * - * @return - * - void - */ + * @brief Indicates that the ota partition has been erased + * By default, this part of flash will be erased during ota. If the behavior of erasing is called in applition, this API needs to be called + * + * @param[in] handle pointer to upgrade handle + */ void ota_data_partition_erase_mark(void *handle); /** @@ -109,4 +99,4 @@ int ota_get_version_number(char *version); } #endif -#endif /*__OTA_PROC_DEFAULT__*/ \ No newline at end of file +#endif /*__OTA_PROC_DEFAULT__*/ diff --git a/docs/Doxyfile b/docs/Doxyfile index f4a06b1dd..0c072bde3 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -22,133 +22,133 @@ PROJECT_NAME = "Espressif Audio Development Framework (ESP-ADF)" INPUT = \ ## Audio Pipeline - ../../components/audio_pipeline/include/audio_element.h \ - ../../components/audio_pipeline/include/audio_pipeline.h \ - ../../components/audio_pipeline/include/audio_event_iface.h \ - ../../components/audio_pipeline/include/audio_common.h \ - ../../components/audio_pipeline/include/ringbuf.h \ + $(PROJECT_PATH)/components/audio_pipeline/include/audio_element.h \ + $(PROJECT_PATH)/components/audio_pipeline/include/audio_pipeline.h \ + $(PROJECT_PATH)/components/audio_pipeline/include/audio_event_iface.h \ + $(PROJECT_PATH)/components/audio_pipeline/include/audio_common.h \ + $(PROJECT_PATH)/components/audio_pipeline/include/ringbuf.h \ ## Audio Stream - ../../components/audio_stream/include/fatfs_stream.h \ - ../../components/audio_stream/include/http_stream.h \ - ../../components/audio_stream/include/i2s_stream.h \ - ../../components/audio_stream/include/raw_stream.h \ - ../../components/audio_stream/include/spiffs_stream.h \ - ../../components/audio_stream/include/tcp_client_stream.h \ - ../../components/audio_stream/include/algorithm_stream.h \ - ../../components/audio_stream/include/pwm_stream.h \ - ../../components/audio_stream/include/tone_stream.h \ - ../../components/audio_stream/include/embed_flash_stream.h \ - ../../components/audio_stream/include/tts_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/fatfs_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/http_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/i2s_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/raw_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/spiffs_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/tcp_client_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/algorithm_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/pwm_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/tone_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/embed_flash_stream.h \ + $(PROJECT_PATH)/components/audio_stream/include/tts_stream.h \ ## ESP Codec - ../../components/esp-adf-libs/esp_codec/include/codec/esp_decoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/audio_type_def.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/esp_decoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/audio_type_def.h \ ## ESP Codec - Decoder - ../../components/esp-adf-libs/esp_codec/include/codec/aac_decoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/amr_decoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/flac_decoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/mp3_decoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/ogg_decoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/opus_decoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/wav_decoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/aac_decoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/amr_decoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/flac_decoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/mp3_decoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/ogg_decoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/opus_decoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/wav_decoder.h \ ## ESP Codec - Encoder - ../../components/esp-adf-libs/esp_codec/include/codec/amrnb_encoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/amrwb_encoder.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/wav_encoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/amrnb_encoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/amrwb_encoder.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/wav_encoder.h \ ## ESP Codec - Auto - ../../components/esp-adf-libs/esp_codec/include/codec/auto_aac_dec.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/auto_amr_dec.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/auto_flac_dec.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/auto_mp3_dec.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/auto_ogg_dec.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/auto_opus_dec.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/auto_wav_dec.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/auto_aac_dec.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/auto_amr_dec.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/auto_flac_dec.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/auto_mp3_dec.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/auto_ogg_dec.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/auto_opus_dec.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/auto_wav_dec.h \ ## Audio Processing - ../../components/esp-adf-libs/esp_codec/include/processing/wav_head.h \ - ../../components/esp-adf-libs/esp_codec/include/processing/esp_downmix.h \ - ../../components/esp-adf-libs/esp_codec/include/processing/esp_equalizer.h \ - ../../components/esp-adf-libs/esp_codec/include/processing/esp_resample.h \ - ../../components/esp-adf-libs/esp_codec/include/processing/esp_sonic.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/processing/wav_head.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/processing/esp_downmix.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/processing/esp_equalizer.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/processing/esp_resample.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/processing/esp_sonic.h \ ## Audio Processing Wrappers - ../../components/esp-adf-libs/esp_codec/include/codec/downmix.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/equalizer.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/filter_resample.h \ - ../../components/esp-adf-libs/esp_codec/include/codec/audio_sonic.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/downmix.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/equalizer.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/filter_resample.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_codec/include/codec/audio_sonic.h \ ## ESP Audio - ../../components/esp-adf-libs/esp_audio/include/audio_def.h \ - ../../components/esp-adf-libs/esp_audio/include/esp_audio.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_audio/include/audio_def.h \ + $(PROJECT_PATH)/components/esp-adf-libs/esp_audio/include/esp_audio.h \ ## Speech Recognition - ../../components/audio_recorder/include/audio_recorder.h \ - ../../components/audio_recorder/include/recorder_encoder.h \ - ../../components/audio_recorder/include/recorder_sr.h \ + $(PROJECT_PATH)/components/audio_recorder/include/audio_recorder.h \ + $(PROJECT_PATH)/components/audio_recorder/include/recorder_encoder.h \ + $(PROJECT_PATH)/components/audio_recorder/include/recorder_sr.h \ ## Common Peripherals - ../../components/esp_peripherals/include/esp_peripherals.h \ - ../../components/esp_peripherals/include/periph_sdcard.h \ - ../../components/esp_peripherals/include/periph_touch.h \ - ../../components/esp_peripherals/include/periph_button.h \ - ../../components/esp_peripherals/include/periph_led.h \ - ../../components/esp_peripherals/include/periph_wifi.h \ - ../../components/esp_peripherals/include/periph_console.h \ - ../../components/esp_peripherals/include/periph_spiffs.h \ - ../../components/esp_peripherals/include/periph_is31fl3216.h \ - ../../components/esp_peripherals/include/periph_adc_button.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/esp_peripherals.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_sdcard.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_touch.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_button.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_led.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_wifi.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_console.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_spiffs.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_is31fl3216.h \ + $(PROJECT_PATH)/components/esp_peripherals/include/periph_adc_button.h \ ## Audio HAL - ../../components/audio_board/include/board_pins_config.h \ - ../../components/audio_hal/driver/es8388/es8388.h \ - ../../components/audio_hal/driver/es8374/es8374.h \ - ../../components/audio_hal/driver/zl38063/zl38063.h \ - ../../components/audio_hal/include/audio_hal.h \ + $(PROJECT_PATH)/components/audio_board/include/board_pins_config.h \ + $(PROJECT_PATH)/components/audio_hal/driver/es8388/es8388.h \ + $(PROJECT_PATH)/components/audio_hal/driver/es8374/es8374.h \ + $(PROJECT_PATH)/components/audio_hal/driver/zl38063/zl38063.h \ + $(PROJECT_PATH)/components/audio_hal/include/audio_hal.h \ ## Audio SAL - ../../components/audio_sal/include/audio_mutex.h \ - ../../components/audio_sal/include/audio_mem.h \ + $(PROJECT_PATH)/components/audio_sal/include/audio_mutex.h \ + $(PROJECT_PATH)/components/audio_sal/include/audio_mem.h \ ## Services - ../../components/bluetooth_service/include/bluetooth_service.h \ - ../../components/bluetooth_service/include/hfp_stream.h \ - ../../components/bluetooth_service/include/bt_keycontrol.h \ - ../../components/bluetooth_service/include/a2dp_stream.h \ - ../../components/input_key_service/include/input_key_service.h \ - ../../components/input_key_service/include/input_key_com_user_id.h \ - ../../components/dueros_service/include/dueros_service.h \ - ../../components/display_service/include/display_service.h \ - ../../components/display_service/led_bar/include/led_bar_aw2013.h \ - ../../components/display_service/led_bar/include/led_bar_is31x.h \ - ../../components/display_service/led_bar/include/led_bar_ws2812.h \ - ../../components/display_service/led_indicator/include/led_indicator.h \ - ../../components/coredump_upload_service/include/coredump_upload_service.h \ - ../../components/battery_service/include/battery_service.h \ - ../../components/battery_service/monitors/include/voltage_monitor.h \ - ../../components/ota_service/include/ota_service.h \ - ../../components/ota_service/include/esp_fs_ota.h \ - ../../components/ota_service/include/ota_proc_default.h \ + $(PROJECT_PATH)/components/bluetooth_service/include/bluetooth_service.h \ + $(PROJECT_PATH)/components/bluetooth_service/include/hfp_stream.h \ + $(PROJECT_PATH)/components/bluetooth_service/include/bt_keycontrol.h \ + $(PROJECT_PATH)/components/bluetooth_service/include/a2dp_stream.h \ + $(PROJECT_PATH)/components/input_key_service/include/input_key_service.h \ + $(PROJECT_PATH)/components/input_key_service/include/input_key_com_user_id.h \ + $(PROJECT_PATH)/components/dueros_service/include/dueros_service.h \ + $(PROJECT_PATH)/components/display_service/include/display_service.h \ + $(PROJECT_PATH)/components/display_service/led_bar/include/led_bar_aw2013.h \ + $(PROJECT_PATH)/components/display_service/led_bar/include/led_bar_is31x.h \ + $(PROJECT_PATH)/components/display_service/led_bar/include/led_bar_ws2812.h \ + $(PROJECT_PATH)/components/display_service/led_indicator/include/led_indicator.h \ + $(PROJECT_PATH)/components/coredump_upload_service/include/coredump_upload_service.h \ + $(PROJECT_PATH)/components/battery_service/include/battery_service.h \ + $(PROJECT_PATH)/components/battery_service/monitors/include/voltage_monitor.h \ + $(PROJECT_PATH)/components/ota_service/include/ota_service.h \ + $(PROJECT_PATH)/components/ota_service/include/esp_fs_ota.h \ + $(PROJECT_PATH)/components/ota_service/include/ota_proc_default.h \ ## Dispatcher framwork - ../../components/esp_dispatcher/include/periph_service.h \ - ../../components/esp_dispatcher/include/audio_service.h \ + $(PROJECT_PATH)/components/esp_dispatcher/include/periph_service.h \ + $(PROJECT_PATH)/components/esp_dispatcher/include/audio_service.h \ ## Cloud Services - ../../components/wifi_service/include/airkiss_config.h \ - ../../components/wifi_service/include/blufi_config.h \ - ../../components/wifi_service/include/smart_config.h \ - ../../components/wifi_service/include/esp_wifi_setting.h \ - ../../components/wifi_service/include/wifi_service.h \ - ../../components/wifi_service/include/wifi_ssid_manager.h \ + $(PROJECT_PATH)/components/wifi_service/include/airkiss_config.h \ + $(PROJECT_PATH)/components/wifi_service/include/blufi_config.h \ + $(PROJECT_PATH)/components/wifi_service/include/smart_config.h \ + $(PROJECT_PATH)/components/wifi_service/include/esp_wifi_setting.h \ + $(PROJECT_PATH)/components/wifi_service/include/wifi_service.h \ + $(PROJECT_PATH)/components/wifi_service/include/wifi_ssid_manager.h \ ## Playlist - ../../components/playlist/include/dram_list.h \ - ../../components/playlist/include/flash_list.h \ - ../../components/playlist/include/partition_list.h \ - ../../components/playlist/include/sdcard_list.h \ - ../../components/playlist/include/playlist.h \ - ../../components/playlist/include/sdcard_scan.h \ + $(PROJECT_PATH)/components/playlist/include/dram_list.h \ + $(PROJECT_PATH)/components/playlist/include/flash_list.h \ + $(PROJECT_PATH)/components/playlist/include/partition_list.h \ + $(PROJECT_PATH)/components/playlist/include/sdcard_list.h \ + $(PROJECT_PATH)/components/playlist/include/playlist.h \ + $(PROJECT_PATH)/components/playlist/include/sdcard_scan.h \ ## Codec Device - ../../components/esp_codec_dev/include/esp_codec_dev.h \ - ../../components/esp_codec_dev/include/esp_codec_dev_vol.h \ - ../../components/esp_codec_dev/include/esp_codec_dev_defaults.h \ - ../../components/esp_codec_dev/include/esp_codec_dev_os.h \ - ../../components/esp_codec_dev/include/esp_codec_dev_types.h \ - ../../components/esp_codec_dev/interface/audio_codec_vol_if.h \ - ../../components/esp_codec_dev/interface/audio_codec_if.h \ - ../../components/esp_codec_dev/interface/audio_codec_gpio_if.h \ - ../../components/esp_codec_dev/interface/audio_codec_data_if.h \ - ../../components/esp_codec_dev/interface/audio_codec_ctrl_if.h \ + $(PROJECT_PATH)/components/esp_codec_dev/include/esp_codec_dev.h \ + $(PROJECT_PATH)/components/esp_codec_dev/include/esp_codec_dev_vol.h \ + $(PROJECT_PATH)/components/esp_codec_dev/include/esp_codec_dev_defaults.h \ + $(PROJECT_PATH)/components/esp_codec_dev/include/esp_codec_dev_os.h \ + $(PROJECT_PATH)/components/esp_codec_dev/include/esp_codec_dev_types.h \ + $(PROJECT_PATH)/components/esp_codec_dev/interface/audio_codec_vol_if.h \ + $(PROJECT_PATH)/components/esp_codec_dev/interface/audio_codec_if.h \ + $(PROJECT_PATH)/components/esp_codec_dev/interface/audio_codec_gpio_if.h \ + $(PROJECT_PATH)/components/esp_codec_dev/interface/audio_codec_data_if.h \ + $(PROJECT_PATH)/components/esp_codec_dev/interface/audio_codec_ctrl_if.h \ ## Audio Mixer - ../../components/audio_mixer/include/audio_mixer.h \ + $(PROJECT_PATH)/components/audio_mixer/include/audio_mixer.h \ ## ## Audio Player ## diff --git a/docs/_static/docs_version.js b/docs/_static/docs_version.js new file mode 100644 index 000000000..b88c9afd7 --- /dev/null +++ b/docs/_static/docs_version.js @@ -0,0 +1,14 @@ +var DOCUMENTATION_VERSIONS = { + DEFAULTS: { has_targets: false, + supported_targets: [ "esp32" ] + }, + VERSIONS: [ + { name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, + ], + IDF_TARGETS: [ + { text: "ESP32", value: "esp32"}, + { text: "ESP32-S2", value: "esp32s2"}, + { text: "ESP32-S3", value: "esp32s3"}, + { text: "ESP32-C3", value: "esp32c3"}, + ] +}; diff --git a/docs/conf_common.py b/docs/conf_common.py index cdc190141..a1beb28f6 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -1,48 +1,57 @@ -# -*- coding: utf-8 -*- -# -# Read the Docs Template documentation build configuration file, created by -# sphinx-quickstart on Tue Aug 26 14:19:49 2014. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - import sys, os -import re -from subprocess import Popen, PIPE -import shlex +from esp_docs.conf_docs import * # noqa: F403,F401 +from local_util import run_cmd_get_output, copy_if_modified # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('..')) -from local_util import run_cmd_get_output, copy_if_modified - builddir = '_build' if 'BUILDDIR' in os.environ: builddir = os.environ['BUILDDIR'] -# Call Doxygen to get XML files from the header files -print("Calling Doxygen to generate latest XML files") -os.system("doxygen ../Doxyfile") -# Doxygen has generated XML files in 'xml' directory. -# Copy them to 'xml_in', only touching the files which have changed. -copy_if_modified('xml/', 'xml_in/') - -# Generate 'api_name.inc' files using the XML files by Doxygen -os.system('python ../gen-dxd.py') - # Generate 'kconfig.inc' file from components' Kconfig files kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir) os.system('python ../gen-kconfig-doc.py > ' + kconfig_inc_path + '.in') copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path) +languages = ['en', 'zh_CN'] + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions += ['link-roles', + 'sphinx_copybutton', + 'sphinxcontrib.wavedrom', + 'esp_docs.esp_extensions.dummy_build_system', + 'esp_docs.esp_extensions.run_doxygen', + ] + +# Disable format_esp_target +extensions.remove('esp_docs.esp_extensions.format_esp_target') + +# Use wavedrompy as backend, instead of wavedrom-cli +render_using_wavedrompy = True + +# link roles config +project_homepage = 'https://github.com/espressif/esp-adf' +github_repo = 'espressif/esp-adf' + +# Context used by sphinx_idf_theme +html_context['github_user'] = 'espressif' +html_context['github_repo'] = 'esp-adf' + +# Extra options required by sphinx_idf_theme +project_slug = 'esp-adf' + +# Final PDF filename will contains target and version +pdf_file_prefix = u'esp-adf' + + +linkcheck_exclude_documents = ['index', # several false positives due to the way we link to different sections + ] + # http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format # suppress_warnings = ['image.nonlocal_uri'] @@ -52,35 +61,6 @@ # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['breathe', - 'link-roles', - 'sphinxcontrib.blockdiag', - 'sphinxcontrib.seqdiag', - 'sphinxcontrib.actdiag', - 'sphinxcontrib.nwdiag', - 'sphinxcontrib.rackdiag', - 'sphinxcontrib.packetdiag', - 'html_redirects' - ] - -# Custom added feature to allow redirecting old URLs -with open('../page_redirects.txt') as f: - lines = [re.sub(' +', ' ', line.strip()) for line in f.readlines() if line.strip() != '' and not line.startswith('#')] - for line in lines: # check for well-formed entries - if len(line.split(' ')) != 2: - raise RuntimeError('Invalid line in page_redirects.txt: %s' % line) -html_redirect_pages = [tuple(line.split(' ')) for line in lines] - -# Breathe extension variables - -# Doxygen regenerates files in 'xml/' directory every time, -# but we copy files to 'xml_in/' only when they change, to speed up -# incremental builds. -breathe_projects = { "esp32-adf": "xml_in/" } -breathe_default_project = "esp32-adf" # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -88,10 +68,6 @@ # The suffix of source filenames. source_suffix = ['.rst', '.md'] -source_parsers = { - '.md': 'recommonmark.parser.CommonMarkParser', - } - # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -155,7 +131,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' +# html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -313,8 +289,3 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False - -# Override RTD CSS theme to introduce the theme corrections -# https://github.com/rtfd/sphinx_rtd_theme/pull/432 -def setup(app): - app.add_stylesheet('theme_overrides.css') diff --git a/docs/en/api-reference/abstraction/audio_hal.rst b/docs/en/api-reference/abstraction/audio_hal.rst index 083617570..061a2ceae 100644 --- a/docs/en/api-reference/abstraction/audio_hal.rst +++ b/docs/en/api-reference/abstraction/audio_hal.rst @@ -9,4 +9,4 @@ The API provides data structures to configure sampling rates of ADC and DAC sign API Reference ------------- -.. include:: /_build/inc/audio_hal.inc +.. include-build-file:: inc/audio_hal.inc diff --git a/docs/en/api-reference/abstraction/es8374.rst b/docs/en/api-reference/abstraction/es8374.rst index 6c7352b34..064350644 100644 --- a/docs/en/api-reference/abstraction/es8374.rst +++ b/docs/en/api-reference/abstraction/es8374.rst @@ -7,4 +7,4 @@ Driver for `ES8374 `_ codec chi API Reference ------------- -.. include:: /_build/inc/es8374.inc +.. include-build-file:: inc/es8374.inc diff --git a/docs/en/api-reference/abstraction/es8388.rst b/docs/en/api-reference/abstraction/es8388.rst index 01eabf610..a85a0c085 100644 --- a/docs/en/api-reference/abstraction/es8388.rst +++ b/docs/en/api-reference/abstraction/es8388.rst @@ -7,4 +7,4 @@ Driver for `ES8388 `_ codec chi API Reference ------------- -.. include:: /_build/inc/es8388.inc +.. include-build-file:: inc/es8388.inc diff --git a/docs/en/api-reference/abstraction/ringbuf.rst b/docs/en/api-reference/abstraction/ringbuf.rst index 5bd7d8e5f..f9b53ce78 100644 --- a/docs/en/api-reference/abstraction/ringbuf.rst +++ b/docs/en/api-reference/abstraction/ringbuf.rst @@ -33,4 +33,4 @@ In most of ESP-ADF :adf:`examples` connecting of Elements with Ringbuffers is do API Reference ------------- -.. include:: /_build/inc/ringbuf.inc +.. include-build-file:: inc/ringbuf.inc diff --git a/docs/en/api-reference/abstraction/zl38063.rst b/docs/en/api-reference/abstraction/zl38063.rst index 89b55f8c2..732ea5b27 100644 --- a/docs/en/api-reference/abstraction/zl38063.rst +++ b/docs/en/api-reference/abstraction/zl38063.rst @@ -7,4 +7,4 @@ Driver for `ZL38063 `, type and API Reference ------------- -.. include:: /_build/inc/audio_common.inc +.. include-build-file:: inc/audio_common.inc diff --git a/docs/en/api-reference/framework/audio_element.rst b/docs/en/api-reference/framework/audio_element.rst index 53fb1f6c4..bb6a25766 100644 --- a/docs/en/api-reference/framework/audio_element.rst +++ b/docs/en/api-reference/framework/audio_element.rst @@ -13,4 +13,4 @@ The available Audio Element types intended for development with this API are lis API Reference ------------- -.. include:: /_build/inc/audio_element.inc +.. include-build-file:: inc/audio_element.inc diff --git a/docs/en/api-reference/framework/audio_event_iface.rst b/docs/en/api-reference/framework/audio_event_iface.rst index 727c422e1..7966868ae 100644 --- a/docs/en/api-reference/framework/audio_event_iface.rst +++ b/docs/en/api-reference/framework/audio_event_iface.rst @@ -13,4 +13,4 @@ Implementation of this API is demonstrated in couple of examples including :exam API Reference ------------- -.. include:: /_build/inc/audio_event_iface.inc +.. include-build-file:: inc/audio_event_iface.inc diff --git a/docs/en/api-reference/framework/audio_pipeline.rst b/docs/en/api-reference/framework/audio_pipeline.rst index 2ee5baa5f..80fba7f33 100644 --- a/docs/en/api-reference/framework/audio_pipeline.rst +++ b/docs/en/api-reference/framework/audio_pipeline.rst @@ -36,4 +36,4 @@ A diagram below presents organization of three elements, HTTP reader stream, MP3 API Reference ------------- -.. include:: /_build/inc/audio_pipeline.inc +.. include-build-file:: inc/audio_pipeline.inc diff --git a/docs/en/api-reference/framework/esp_audio.rst b/docs/en/api-reference/framework/esp_audio.rst index cce894100..27f0021f1 100644 --- a/docs/en/api-reference/framework/esp_audio.rst +++ b/docs/en/api-reference/framework/esp_audio.rst @@ -7,6 +7,6 @@ This component provides several simple high level APIs. It is intended for quick API Reference ------------- -.. include:: /_build/inc/audio_def.inc +.. include-build-file:: inc/audio_def.inc -.. include:: /_build/inc/esp_audio.inc +.. include-build-file:: inc/esp_audio.inc diff --git a/docs/en/api-reference/kconfig.rst b/docs/en/api-reference/kconfig.rst index 508a3899f..182181eec 100644 --- a/docs/en/api-reference/kconfig.rst +++ b/docs/en/api-reference/kconfig.rst @@ -3,4 +3,4 @@ Configuration Options Compile-time configuration options specific to ESP-ADF. -.. include:: /_build/inc/kconfig.inc +.. include-build-file:: inc/kconfig.inc diff --git a/docs/en/api-reference/peripherals/esp_peripherals.rst b/docs/en/api-reference/peripherals/esp_peripherals.rst index de8a56067..ebf476f6a 100644 --- a/docs/en/api-reference/peripherals/esp_peripherals.rst +++ b/docs/en/api-reference/peripherals/esp_peripherals.rst @@ -16,4 +16,4 @@ Please refer to :example_file:`player/pipeline_http_mp3/main/play_http_mp3_examp API Reference ------------- -.. include:: /_build/inc/esp_peripherals.inc +.. include-build-file:: inc/esp_peripherals.inc diff --git a/docs/en/api-reference/peripherals/periph_adc_button.rst b/docs/en/api-reference/peripherals/periph_adc_button.rst index 0d35aa868..bd55aa16c 100644 --- a/docs/en/api-reference/peripherals/periph_adc_button.rst +++ b/docs/en/api-reference/peripherals/periph_adc_button.rst @@ -15,4 +15,4 @@ Implementation of this API is demonstrated in the following example: API Reference ------------- -.. include:: /_build/inc/periph_adc_button.inc +.. include-build-file:: inc/periph_adc_button.inc diff --git a/docs/en/api-reference/peripherals/periph_button.rst b/docs/en/api-reference/peripherals/periph_button.rst index 36a657028..e73d1f6b0 100644 --- a/docs/en/api-reference/peripherals/periph_button.rst +++ b/docs/en/api-reference/peripherals/periph_button.rst @@ -13,4 +13,4 @@ Implementation of this API is demonstrated in :example:`cloud_services/google_tr API Reference ------------- -.. include:: /_build/inc/periph_button.inc +.. include-build-file:: inc/periph_button.inc diff --git a/docs/en/api-reference/peripherals/periph_console.rst b/docs/en/api-reference/peripherals/periph_console.rst index 8f3a699b6..0dec54d1b 100644 --- a/docs/en/api-reference/peripherals/periph_console.rst +++ b/docs/en/api-reference/peripherals/periph_console.rst @@ -14,4 +14,4 @@ Please refer to :example_file:`cli/main/console_example.c`. API Reference ------------- -.. include:: /_build/inc/periph_console.inc +.. include-build-file:: inc/periph_console.inc diff --git a/docs/en/api-reference/peripherals/periph_is31fl3216.rst b/docs/en/api-reference/peripherals/periph_is31fl3216.rst index 1da9f892d..6a43ff791 100644 --- a/docs/en/api-reference/peripherals/periph_is31fl3216.rst +++ b/docs/en/api-reference/peripherals/periph_is31fl3216.rst @@ -14,4 +14,4 @@ Implementation of this API is demonstrated in :example:`checks/check_display_led API Reference ------------- -.. include:: /_build/inc/periph_is31fl3216.inc +.. include-build-file:: inc/periph_is31fl3216.inc diff --git a/docs/en/api-reference/peripherals/periph_led.rst b/docs/en/api-reference/peripherals/periph_led.rst index ae00b4845..ece013855 100644 --- a/docs/en/api-reference/peripherals/periph_led.rst +++ b/docs/en/api-reference/peripherals/periph_led.rst @@ -16,4 +16,4 @@ Implementation of this API is demonstrated in couple of examples: API Reference ------------- -.. include:: /_build/inc/periph_led.inc +.. include-build-file:: inc/periph_led.inc diff --git a/docs/en/api-reference/peripherals/periph_sdcard.rst b/docs/en/api-reference/peripherals/periph_sdcard.rst index 0deec7089..bb89a91c9 100644 --- a/docs/en/api-reference/peripherals/periph_sdcard.rst +++ b/docs/en/api-reference/peripherals/periph_sdcard.rst @@ -18,5 +18,5 @@ Implementation of this API is demonstrated in couple of examples: API Reference ------------- -.. include:: /_build/inc/periph_sdcard.inc +.. include-build-file:: inc/periph_sdcard.inc diff --git a/docs/en/api-reference/peripherals/periph_spiffs.rst b/docs/en/api-reference/peripherals/periph_spiffs.rst index 6fea907ab..be739cde7 100644 --- a/docs/en/api-reference/peripherals/periph_spiffs.rst +++ b/docs/en/api-reference/peripherals/periph_spiffs.rst @@ -13,5 +13,5 @@ Implementation of this API is demonstrated in :example:`audio_processing/pipelin API Reference ------------- -.. include:: /_build/inc/periph_spiffs.inc +.. include-build-file:: inc/periph_spiffs.inc diff --git a/docs/en/api-reference/peripherals/periph_touch.rst b/docs/en/api-reference/peripherals/periph_touch.rst index ecb2eaf76..9abd47f86 100644 --- a/docs/en/api-reference/peripherals/periph_touch.rst +++ b/docs/en/api-reference/peripherals/periph_touch.rst @@ -13,5 +13,5 @@ Implementation of this API is demonstrated in :example:`get-started/play_mp3_con API Reference ------------- -.. include:: /_build/inc/periph_touch.inc +.. include-build-file:: inc/periph_touch.inc diff --git a/docs/en/api-reference/peripherals/periph_wifi.rst b/docs/en/api-reference/peripherals/periph_wifi.rst index de5242b8b..9f179e7fc 100644 --- a/docs/en/api-reference/peripherals/periph_wifi.rst +++ b/docs/en/api-reference/peripherals/periph_wifi.rst @@ -13,5 +13,5 @@ Implementation of this API is demonstrated in :example:`player/pipeline_http_mp3 API Reference ------------- -.. include:: /_build/inc/periph_wifi.inc +.. include-build-file:: inc/periph_wifi.inc diff --git a/docs/en/api-reference/playlist/index.rst b/docs/en/api-reference/playlist/index.rst index 0aa480143..5f95e1c38 100644 --- a/docs/en/api-reference/playlist/index.rst +++ b/docs/en/api-reference/playlist/index.rst @@ -29,7 +29,7 @@ Application Example - :example:`cli` -.. include:: /_build/inc/sdcard_scan.inc +.. include-build-file:: inc/sdcard_scan.inc Saving Playlist @@ -47,7 +47,7 @@ Application Example - :example:`player/pipeline_sdcard_mp3_control` - :example:`cli` -.. include:: /_build/inc/sdcard_list.inc +.. include-build-file:: inc/sdcard_list.inc Saving to DRAM @@ -55,7 +55,7 @@ Saving to DRAM The playlist can be stored in DRAM. Functions, such as those to save and display the playlist, can be called through the ``playlist_operator_handle_t`` handle. -.. include:: /_build/inc/dram_list.inc +.. include-build-file:: inc/dram_list.inc Saving to NVS Partition in Flash @@ -63,7 +63,7 @@ Saving to NVS Partition in Flash The playlist can be stored in the `NVS partition `_ in flash. Functions, such as those to save and display the playlist, can be called through the ``playlist_operator_handle_t`` handle. -.. include:: /_build/inc/flash_list.inc +.. include-build-file:: inc/flash_list.inc Saving to ``DATA_UNDEFINED`` Partition in Flash @@ -71,7 +71,7 @@ Saving to ``DATA_UNDEFINED`` Partition in Flash The playlist can be stored in the ``DATA_UNDEFINED`` partition (see `Partition Tables `_ for details) in flash. Functions, such as those to save and display the playlist, can be called through the ``playlist_operator_handle_t`` handle. Please add the two partitions whose subtypes are 0x06 and 0x07 to the flash partition table first. -.. include:: /_build/inc/partition_list.inc +.. include-build-file:: inc/partition_list.inc Playlist Manager @@ -79,4 +79,4 @@ Playlist Manager Playlist Manager manages the above playlists and can add multiple playlist instances to the ``playlist_handle_t`` handle. -.. include:: /_build/inc/playlist.inc \ No newline at end of file +.. include-build-file:: inc/playlist.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/battery_service.rst b/docs/en/api-reference/services/battery_service.rst index 8f8e1ac7e..efed806de 100644 --- a/docs/en/api-reference/services/battery_service.rst +++ b/docs/en/api-reference/services/battery_service.rst @@ -14,5 +14,5 @@ Implementation of this API is demonstrated in the following example: * :example:`system/battery` -.. include:: /_build/inc/battery_service.inc -.. include:: /_build/inc/voltage_monitor.inc \ No newline at end of file +.. include-build-file:: inc/battery_service.inc +.. include-build-file:: inc/voltage_monitor.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/bluetooth_service.rst b/docs/en/api-reference/services/bluetooth_service.rst index 17b7cc7f8..0c84d53ef 100644 --- a/docs/en/api-reference/services/bluetooth_service.rst +++ b/docs/en/api-reference/services/bluetooth_service.rst @@ -18,7 +18,7 @@ Implementation of this API is demonstrated in the following example: * :example:`player/pipeline_bt_sink` -.. include:: /_build/inc/bluetooth_service.inc -.. include:: /_build/inc/bt_keycontrol.inc -.. include:: /_build/inc/hfp_stream.inc -.. include:: /_build/inc/a2dp_stream.inc \ No newline at end of file +.. include-build-file:: inc/bluetooth_service.inc +.. include-build-file:: inc/bt_keycontrol.inc +.. include-build-file:: inc/hfp_stream.inc +.. include-build-file:: inc/a2dp_stream.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/coredump_upload_service.rst b/docs/en/api-reference/services/coredump_upload_service.rst index c4e9f44a0..d8ce2ae70 100644 --- a/docs/en/api-reference/services/coredump_upload_service.rst +++ b/docs/en/api-reference/services/coredump_upload_service.rst @@ -14,4 +14,4 @@ Implementation of this API is demonstrated in the following example: * :example:`system/coredump` -.. include:: /_build/inc/coredump_upload_service.inc \ No newline at end of file +.. include-build-file:: inc/coredump_upload_service.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/display_service.rst b/docs/en/api-reference/services/display_service.rst index 07533dcd4..b25557f40 100644 --- a/docs/en/api-reference/services/display_service.rst +++ b/docs/en/api-reference/services/display_service.rst @@ -16,8 +16,8 @@ Implementation of this API is demonstrated in the following example: * :example:`checks/check_display_led` -.. include:: /_build/inc/display_service.inc -.. include:: /_build/inc/led_bar_aw2013.inc -.. include:: /_build/inc/led_bar_is31x.inc -.. include:: /_build/inc/led_bar_ws2812.inc -.. include:: /_build/inc/led_indicator.inc \ No newline at end of file +.. include-build-file:: inc/display_service.inc +.. include-build-file:: inc/led_bar_aw2013.inc +.. include-build-file:: inc/led_bar_is31x.inc +.. include-build-file:: inc/led_bar_ws2812.inc +.. include-build-file:: inc/led_indicator.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/dueros_service.rst b/docs/en/api-reference/services/dueros_service.rst index e1533ee9c..47c76d123 100644 --- a/docs/en/api-reference/services/dueros_service.rst +++ b/docs/en/api-reference/services/dueros_service.rst @@ -14,4 +14,4 @@ Implementation of this API is demonstrated in the following example: * :example:`dueros` -.. include:: /_build/inc/dueros_service.inc \ No newline at end of file +.. include-build-file:: inc/dueros_service.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/index.rst b/docs/en/api-reference/services/index.rst index 7b35958b7..518c13867 100644 --- a/docs/en/api-reference/services/index.rst +++ b/docs/en/api-reference/services/index.rst @@ -27,5 +27,5 @@ For details please refer to descriptions listed below. Core Dump Upload Service -.. include:: /_build/inc/periph_service.inc -.. include:: /_build/inc/audio_service.inc \ No newline at end of file +.. include-build-file:: inc/periph_service.inc +.. include-build-file:: inc/audio_service.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/input_key_service.rst b/docs/en/api-reference/services/input_key_service.rst index 2244a4806..f11b38615 100644 --- a/docs/en/api-reference/services/input_key_service.rst +++ b/docs/en/api-reference/services/input_key_service.rst @@ -15,5 +15,5 @@ Implementation of this API is demonstrated in the following example: * :example:`player/pipeline_sdcard_mp3_control` * :example:`protocols/voip` -.. include:: /_build/inc/input_key_service.inc -.. include:: /_build/inc/input_key_com_user_id.inc \ No newline at end of file +.. include-build-file:: inc/input_key_service.inc +.. include-build-file:: inc/input_key_com_user_id.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/ota_service.rst b/docs/en/api-reference/services/ota_service.rst index 7f993142e..fe1833a0b 100644 --- a/docs/en/api-reference/services/ota_service.rst +++ b/docs/en/api-reference/services/ota_service.rst @@ -13,6 +13,6 @@ Implementation of this API is demonstrated in the following example: * :example:`ota` -.. include:: /_build/inc/ota_service.inc -.. include:: /_build/inc/ota_proc_default.inc -.. include:: /_build/inc/esp_fs_ota.inc \ No newline at end of file +.. include-build-file:: inc/ota_service.inc +.. include-build-file:: inc/ota_proc_default.inc +.. include-build-file:: inc/esp_fs_ota.inc \ No newline at end of file diff --git a/docs/en/api-reference/services/wifi_service.rst b/docs/en/api-reference/services/wifi_service.rst index 2d2876d5b..771c0013f 100644 --- a/docs/en/api-reference/services/wifi_service.rst +++ b/docs/en/api-reference/services/wifi_service.rst @@ -13,9 +13,9 @@ Implementation of this API is demonstrated in the following example: * :example:`dueros` -.. include:: /_build/inc/wifi_service.inc -.. include:: /_build/inc/esp_wifi_setting.inc -.. include:: /_build/inc/smart_config.inc -.. include:: /_build/inc/blufi_config.inc -.. include:: /_build/inc/airkiss_config.inc -.. include:: /_build/inc/wifi_ssid_manager.inc \ No newline at end of file +.. include-build-file:: inc/wifi_service.inc +.. include-build-file:: inc/esp_wifi_setting.inc +.. include-build-file:: inc/smart_config.inc +.. include-build-file:: inc/blufi_config.inc +.. include-build-file:: inc/airkiss_config.inc +.. include-build-file:: inc/wifi_ssid_manager.inc \ No newline at end of file diff --git a/docs/en/api-reference/speech-recognition/audio_recorder.rst b/docs/en/api-reference/speech-recognition/audio_recorder.rst index b7813e801..cbb055773 100644 --- a/docs/en/api-reference/speech-recognition/audio_recorder.rst +++ b/docs/en/api-reference/speech-recognition/audio_recorder.rst @@ -47,7 +47,7 @@ The :example:`speech_recognition/wwe/` example demonstrates how to initialize th API Reference ------------- -.. include:: /_build/inc/audio_recorder.inc -.. include:: /_build/inc/recorder_sr.inc -.. include:: /_build/inc/recorder_encoder.inc +.. include-build-file:: inc/audio_recorder.inc +.. include-build-file:: inc/recorder_sr.inc +.. include-build-file:: inc/recorder_encoder.inc diff --git a/docs/en/api-reference/streams/index.rst b/docs/en/api-reference/streams/index.rst index 05292d394..e247d7455 100644 --- a/docs/en/api-reference/streams/index.rst +++ b/docs/en/api-reference/streams/index.rst @@ -30,7 +30,7 @@ Application Example - :example_file:`advanced_examples/algorithm/main/algorithm_examples.c` - :example_file:`protocols/voip/main/voip_app.c` -.. include:: /_build/inc/algorithm_stream.inc +.. include-build-file:: inc/algorithm_stream.inc .. _api-reference-stream_fatfs: @@ -47,7 +47,7 @@ Application Example - Reader example: :example:`player/pipeline_play_sdcard_music` - Writer example: :example:`recorder/pipeline_recording_to_sdcard` -.. include:: /_build/inc/fatfs_stream.inc +.. include-build-file:: inc/fatfs_stream.inc .. _api-reference-stream_http: @@ -70,7 +70,7 @@ Application Example - :example:`recorder/pipeline_raw_http` -.. include:: /_build/inc/http_stream.inc +.. include-build-file:: inc/http_stream.inc .. _api-reference-stream_i2s: @@ -86,7 +86,7 @@ Application Example - Reader example: :example:`recorder/pipeline_wav_amr_sdcard` - Writer example: :example:`get-started/play_mp3_control` -.. include:: /_build/inc/i2s_stream.inc +.. include-build-file:: inc/i2s_stream.inc .. _api-reference-stream_pwm: @@ -103,7 +103,7 @@ Application Example - Writer example: :example:`player/pipeline_play_mp3_with_dac_or_pwm` -.. include:: /_build/inc/pwm_stream.inc +.. include-build-file:: inc/pwm_stream.inc .. _api-reference-stream_raw: @@ -121,7 +121,7 @@ Application Example - Writer example: :example:`advanced_examples/downmix_pipeline` -.. include:: /_build/inc/raw_stream.inc +.. include-build-file:: inc/raw_stream.inc .. _api-reference-stream_spiffs: @@ -137,7 +137,7 @@ Application Example - :example:`player/pipeline_spiffs_mp3` -.. include:: /_build/inc/spiffs_stream.inc +.. include-build-file:: inc/spiffs_stream.inc .. _api-reference-stream_tcp_client: @@ -154,7 +154,7 @@ Application Example - :example:`get-started/pipeline_tcp_client` -.. include:: /_build/inc/tcp_client_stream.inc +.. include-build-file:: inc/tcp_client_stream.inc .. _api-reference-stream_tone: @@ -171,7 +171,7 @@ Application Example - :example:`player/pipeline_flash_tone` -.. include:: /_build/inc/tone_stream.inc +.. include-build-file:: inc/tone_stream.inc .. _api-reference-embed_flash: @@ -188,7 +188,7 @@ Application Example - :example:`player/pipeline_embed_flash_tone` -.. include:: /_build/inc/embed_flash_stream.inc +.. include-build-file:: inc/embed_flash_stream.inc .. _api-reference-stream_tts: @@ -204,4 +204,4 @@ Application Example - Reader example: :example:`player/pipeline_tts_stream` -.. include:: /_build/inc/tts_stream.inc +.. include-build-file:: inc/tts_stream.inc diff --git a/docs/en/conf.py b/docs/en/conf.py index ab5438c73..2e7443577 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -11,10 +11,14 @@ sys.path.insert(0, os.path.abspath('..')) from conf_common import * # noqa: F401, F403 - need to make available everything from common from local_util import download_file_if_missing # noqa: E402 - need to import from common folder +import datetime + +current_year = datetime.datetime.now().year # General information about the project. project = u'Audio Development Framework' -copyright = u'2016 - 2019, Espressif Systems (Shanghai) CO., LTD' +copyright = u'2017 - {}, Espressif Systems (Shanghai) Co., Ltd.'.format(current_year) +pdf_title = u'Audio Development Framework Handbook' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/link-roles.py b/docs/link-roles.py index c10eb8c4d..0f0331e3a 100644 --- a/docs/link-roles.py +++ b/docs/link-roles.py @@ -57,12 +57,6 @@ def setup(app): app.add_role('adf', github_link('tree', rev, submods, '/', app.config)) app.add_role('adf_file', github_link('blob', rev, submods, '/', app.config)) app.add_role('adf_raw', github_link('raw', rev, submods, '/', app.config)) - app.add_role('component', github_link('tree', rev, submods, '/components/', app.config)) - app.add_role('component_file', github_link('blob', rev, submods, '/components/', app.config)) - app.add_role('component_raw', github_link('raw', rev, submods, '/components/', app.config)) - app.add_role('example', github_link('tree', rev, submods, '/examples/', app.config)) - app.add_role('example_file', github_link('blob', rev, submods, '/examples/', app.config)) - app.add_role('example_raw', github_link('raw', rev, submods, '/examples/', app.config)) # link to the current documentation file in specific language version on_rtd = os.environ.get('READTHEDOCS', None) == 'True' @@ -75,8 +69,6 @@ def setup(app): # if not on the RTD then provide generic identification tag_rev = run_cmd_get_output('git describe --always') - app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev))) - def url_join(*url_parts): """ Make a URL out of multiple components, assume first part is the https:// part and @@ -142,7 +134,7 @@ def crosslink(pattern): def role(name, rawtext, text, lineno, inliner, options={}, content=[]): (language, link_text) = text.split(':') docname = inliner.document.settings.env.docname - doc_path = inliner.document.settings.env.doc2path(docname, None, None) + doc_path = inliner.document.settings.env.doc2path(docname) return_path = '../' * doc_path.count('/') url = pattern % (return_path, language, docname) node = nodes.reference(rawtext, link_text, refuri=url, **options) diff --git a/docs/requirements.txt b/docs/requirements.txt index a800e69f7..d8576bba4 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,17 +1,6 @@ # This is a list of python packages used to generate documentation. This file is used with pip: # pip install --user -r requirements.txt # -setuptools<58 -sphinx==2.3.1 -breathe==4.14.1 -sphinx-rtd-theme==1.0.0 -sphinx-notfound-page==0.7.1 -sphinxcontrib-blockdiag==2.0.0 -sphinxcontrib-seqdiag==2.0.0 -sphinxcontrib-actdiag==2.0.0 -sphinxcontrib-nwdiag==2.0.0 -sphinxcontrib-wavedrom==2.0.0 -nwdiag==2.0.0 -recommonmark==0.7.0 -# for ../tools/gen_esp_err_to_name.py -future==0.16.0 \ No newline at end of file + +esp-docs==1.* +sphinx-design==0.2.0 diff --git a/docs/zh_CN/api-reference/playlist/index.rst b/docs/zh_CN/api-reference/playlist/index.rst index bad35d6cd..af4051657 100644 --- a/docs/zh_CN/api-reference/playlist/index.rst +++ b/docs/zh_CN/api-reference/playlist/index.rst @@ -29,7 +29,7 @@ - :example:`cli` -.. include:: /_build/inc/sdcard_scan.inc +.. include-build-file:: inc/sdcard_scan.inc 存储播放列表 @@ -47,7 +47,7 @@ - :example:`player/pipeline_sdcard_mp3_control` - :example:`cli` -.. include:: /_build/inc/sdcard_list.inc +.. include-build-file:: inc/sdcard_list.inc 存储至 DRAM @@ -55,7 +55,7 @@ 播放列表可存储至 DRAM 中，并通过 ``playlist_operator_handle_t`` 句柄调用相应函数来实现保存、显示播放列表等功能。 -.. include:: /_build/inc/dram_list.inc +.. include-build-file:: inc/dram_list.inc 存储至 flash 的 NVS 分区 @@ -63,7 +63,7 @@ 播放列表可存储至 flash 的 `NVS 分区 `_ 中，并通过 ``playlist_operator_handle_t`` 句柄调用相应函数来实现保存、显示播放列表等功能。 -.. include:: /_build/inc/flash_list.inc +.. include-build-file:: inc/flash_list.inc 存储至 flash 的 ``DATA_UNDEFINED`` 分区 @@ -71,7 +71,7 @@ 播放列表可存储至 flash 的 ``DATA_UNDEFINED`` 分区中（详情请参考 `分区表 `_），并通过 ``playlist_operator_handle_t`` 句柄调用相应函数来实现保存、显示播放列表等功能。需要先将子类型为 0x06 和 0x07 的 2 个分区添加到 flash 的分区表中。 -.. include:: /_build/inc/partition_list.inc +.. include-build-file:: inc/partition_list.inc 播放列表管理器 @@ -79,4 +79,4 @@ 播放列表管理器用于管理上述播放列表，可将多个播放列表实例添加到 ``playlist_handle_t`` 句柄。 -.. include:: /_build/inc/playlist.inc \ No newline at end of file +.. include-build-file:: inc/playlist.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/battery_service.rst b/docs/zh_CN/api-reference/services/battery_service.rst index 51cb29af2..156f36238 100644 --- a/docs/zh_CN/api-reference/services/battery_service.rst +++ b/docs/zh_CN/api-reference/services/battery_service.rst @@ -14,5 +14,5 @@ * :example:`system/battery` -.. include:: /_build/inc/battery_service.inc -.. include:: /_build/inc/voltage_monitor.inc \ No newline at end of file +.. include-build-file:: inc/battery_service.inc +.. include-build-file:: inc/voltage_monitor.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/bluetooth_service.rst b/docs/zh_CN/api-reference/services/bluetooth_service.rst index 31b7758b9..8bbc3b9e5 100644 --- a/docs/zh_CN/api-reference/services/bluetooth_service.rst +++ b/docs/zh_CN/api-reference/services/bluetooth_service.rst @@ -18,7 +18,7 @@ * :example:`player/pipeline_bt_sink` -.. include:: /_build/inc/bluetooth_service.inc -.. include:: /_build/inc/bt_keycontrol.inc -.. include:: /_build/inc/hfp_stream.inc -.. include:: /_build/inc/a2dp_stream.inc \ No newline at end of file +.. include-build-file:: inc/bluetooth_service.inc +.. include-build-file:: inc/bt_keycontrol.inc +.. include-build-file:: inc/hfp_stream.inc +.. include-build-file:: inc/a2dp_stream.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/coredump_upload_service.rst b/docs/zh_CN/api-reference/services/coredump_upload_service.rst index e4568add5..69cf9ad67 100644 --- a/docs/zh_CN/api-reference/services/coredump_upload_service.rst +++ b/docs/zh_CN/api-reference/services/coredump_upload_service.rst @@ -14,4 +14,4 @@ * :example:`system/coredump` -.. include:: /_build/inc/coredump_upload_service.inc \ No newline at end of file +.. include-build-file:: inc/coredump_upload_service.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/display_service.rst b/docs/zh_CN/api-reference/services/display_service.rst index ea940da4a..9c04cdf4f 100644 --- a/docs/zh_CN/api-reference/services/display_service.rst +++ b/docs/zh_CN/api-reference/services/display_service.rst @@ -16,8 +16,8 @@ * :example:`checks/check_display_led` -.. include:: /_build/inc/display_service.inc -.. include:: /_build/inc/led_bar_aw2013.inc -.. include:: /_build/inc/led_bar_is31x.inc -.. include:: /_build/inc/led_bar_ws2812.inc -.. include:: /_build/inc/led_indicator.inc \ No newline at end of file +.. include-build-file:: inc/display_service.inc +.. include-build-file:: inc/led_bar_aw2013.inc +.. include-build-file:: inc/led_bar_is31x.inc +.. include-build-file:: inc/led_bar_ws2812.inc +.. include-build-file:: inc/led_indicator.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/dueros_service.rst b/docs/zh_CN/api-reference/services/dueros_service.rst index 6b9697af7..1006a848a 100644 --- a/docs/zh_CN/api-reference/services/dueros_service.rst +++ b/docs/zh_CN/api-reference/services/dueros_service.rst @@ -14,4 +14,4 @@ DuerOS 服务 (DuerOS service) 实现了 DuerOS 的语音交互。 * :example:`dueros` -.. include:: /_build/inc/dueros_service.inc \ No newline at end of file +.. include-build-file:: inc/dueros_service.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/index.rst b/docs/zh_CN/api-reference/services/index.rst index 1805e4b5b..27b53789d 100644 --- a/docs/zh_CN/api-reference/services/index.rst +++ b/docs/zh_CN/api-reference/services/index.rst @@ -27,5 +27,5 @@ 核心转储上传服务 -.. include:: /_build/inc/periph_service.inc -.. include:: /_build/inc/audio_service.inc \ No newline at end of file +.. include-build-file:: inc/periph_service.inc +.. include-build-file:: inc/audio_service.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/input_key_service.rst b/docs/zh_CN/api-reference/services/input_key_service.rst index bce5244ed..7b6560565 100644 --- a/docs/zh_CN/api-reference/services/input_key_service.rst +++ b/docs/zh_CN/api-reference/services/input_key_service.rst @@ -15,5 +15,5 @@ * :example:`player/pipeline_sdcard_mp3_control` * :example:`protocols/voip` -.. include:: /_build/inc/input_key_service.inc -.. include:: /_build/inc/input_key_com_user_id.inc \ No newline at end of file +.. include-build-file:: inc/input_key_service.inc +.. include-build-file:: inc/input_key_com_user_id.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/ota_service.rst b/docs/zh_CN/api-reference/services/ota_service.rst index 98f639e3e..637cd81e8 100644 --- a/docs/zh_CN/api-reference/services/ota_service.rst +++ b/docs/zh_CN/api-reference/services/ota_service.rst @@ -13,6 +13,6 @@ OTA 服务 (OTA service) 提供对固件进行 OTA 的功能，支持从本地 * :example:`ota` -.. include:: /_build/inc/ota_service.inc -.. include:: /_build/inc/ota_proc_default.inc -.. include:: /_build/inc/esp_fs_ota.inc \ No newline at end of file +.. include-build-file:: inc/ota_service.inc +.. include-build-file:: inc/ota_proc_default.inc +.. include-build-file:: inc/esp_fs_ota.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/services/wifi_service.rst b/docs/zh_CN/api-reference/services/wifi_service.rst index a68982ac4..8fddb281c 100644 --- a/docs/zh_CN/api-reference/services/wifi_service.rst +++ b/docs/zh_CN/api-reference/services/wifi_service.rst @@ -13,9 +13,9 @@ Wi-Fi 服务 (Wi-Fi service) 提供了网络配置和网络管理的功能。配 * :example:`dueros` -.. include:: /_build/inc/wifi_service.inc -.. include:: /_build/inc/esp_wifi_setting.inc -.. include:: /_build/inc/smart_config.inc -.. include:: /_build/inc/blufi_config.inc -.. include:: /_build/inc/airkiss_config.inc -.. include:: /_build/inc/wifi_ssid_manager.inc \ No newline at end of file +.. include-build-file:: inc/wifi_service.inc +.. include-build-file:: inc/esp_wifi_setting.inc +.. include-build-file:: inc/smart_config.inc +.. include-build-file:: inc/blufi_config.inc +.. include-build-file:: inc/airkiss_config.inc +.. include-build-file:: inc/wifi_ssid_manager.inc \ No newline at end of file diff --git a/docs/zh_CN/api-reference/streams/index.rst b/docs/zh_CN/api-reference/streams/index.rst index a5a3ef157..8b0e10241 100644 --- a/docs/zh_CN/api-reference/streams/index.rst +++ b/docs/zh_CN/api-reference/streams/index.rst @@ -30,7 +30,7 @@ - :example_file:`advanced_examples/algorithm/main/algorithm_examples.c` - :example_file:`protocols/voip/main/voip_app.c` -.. include:: /_build/inc/algorithm_stream.inc +.. include-build-file:: inc/algorithm_stream.inc .. _api-reference-stream_fatfs: @@ -47,7 +47,7 @@ FatFs 流从 FatFs 文件系统中读取和写入数据，具有读和写两种 - 读类型示例：:example:`player/pipeline_play_sdcard_music` - 写类型示例：:example:`recorder/pipeline_recording_to_sdcard` -.. include:: /_build/inc/fatfs_stream.inc +.. include-build-file:: inc/fatfs_stream.inc .. _api-reference-stream_http: @@ -70,7 +70,7 @@ HTTP 流通过 :cpp:func:`esp_http_client` 获取和发送数据，具有读和 - :example:`recorder/pipeline_raw_http` -.. include:: /_build/inc/http_stream.inc +.. include-build-file:: inc/http_stream.inc .. _api-reference-stream_i2s: @@ -86,7 +86,7 @@ I2S 流通过芯片的 I2S、PDM、ADC、DAC 接口接收和发送音频数据 - 读类型示例：:example:`recorder/pipeline_wav_amr_sdcard` - 写类型示例：:example:`get-started/play_mp3_control` -.. include:: /_build/inc/i2s_stream.inc +.. include-build-file:: inc/i2s_stream.inc .. _api-reference-stream_pwm: @@ -103,7 +103,7 @@ PWM 流 - 写类型示例：:example:`player/pipeline_play_mp3_with_dac_or_pwm` -.. include:: /_build/inc/pwm_stream.inc +.. include-build-file:: inc/pwm_stream.inc .. _api-reference-stream_raw: @@ -121,7 +121,7 @@ PWM 流 - 写类型示例：:example:`advanced_examples/downmix_pipeline` -.. include:: /_build/inc/raw_stream.inc +.. include-build-file:: inc/raw_stream.inc .. _api-reference-stream_spiffs: @@ -138,7 +138,7 @@ SPIFFS 流从 SPIFFS 读取和写入音频数据。 - :example:`player/pipeline_spiffs_mp3` -.. include:: /_build/inc/spiffs_stream.inc +.. include-build-file:: inc/spiffs_stream.inc .. _api-reference-stream_tcp_client: @@ -155,7 +155,7 @@ TCP 客户端流 (TCP client stream) 通过 TCP 读取和写入服务器数据 - :example:`get-started/pipeline_tcp_client` -.. include:: /_build/inc/tcp_client_stream.inc +.. include-build-file:: inc/tcp_client_stream.inc .. _api-reference-stream_tone: @@ -172,7 +172,7 @@ TCP 客户端流 (TCP client stream) 通过 TCP 读取和写入服务器数据 - :example:`player/pipeline_flash_tone` -.. include:: /_build/inc/tone_stream.inc +.. include-build-file:: inc/tone_stream.inc .. _api-reference-embed_flash: @@ -189,7 +189,7 @@ TCP 客户端流 (TCP client stream) 通过 TCP 读取和写入服务器数据 - :example:`player/pipeline_embed_flash_tone` -.. include:: /_build/inc/embed_flash_stream.inc +.. include-build-file:: inc/embed_flash_stream.inc .. _api-reference-stream_tts: @@ -205,4 +205,4 @@ TCP 客户端流 (TCP client stream) 通过 TCP 读取和写入服务器数据 - 读类型示例：:example:`player/pipeline_tts_stream` -.. include:: /_build/inc/tts_stream.inc +.. include-build-file:: inc/tts_stream.inc diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index 71ae3c52b..cabf3b5b6 100644 --- a/docs/zh_CN/conf.py +++ b/docs/zh_CN/conf.py @@ -11,10 +11,14 @@ sys.path.insert(0, os.path.abspath('..')) from conf_common import * # noqa: F401, F403 - need to make available everything from common from local_util import download_file_if_missing # noqa: E402 - need to import from common folder +import datetime + +current_year = datetime.datetime.now().year # General information about the project. project = u'ADF 音频应用开发框架' -copyright = u'2016 - 2019 乐鑫信息科技（上海）股份有限公司' +copyright = u'2017 - {}, 乐鑫信息科技（上海）股份有限公司'.format(current_year) +pdf_title = u'ADF 音频应用开发框架手册' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/tools/ci/utils.sh b/tools/ci/utils.sh index ea4976294..559f42512 100644 --- a/tools/ci/utils.sh +++ b/tools/ci/utils.sh @@ -24,6 +24,14 @@ function add_github_ssh_keys() { echo -e "Host github.com\n\tStrictHostKeyChecking no\n" >>~/.ssh/config } +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 common_before_scripts() { source $IDF_PATH/tools/ci/utils.sh is_based_on_commits $REQUIRED_ANCESTOR_COMMITS