diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index a480e580b..4989fa7eb 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -175,16 +175,31 @@ build_docs: tags: - build_docs artifacts: + when: always paths: + - docs/doxygen-warning-log.txt + - docs/sphinx-warning-log.txt - docs/_build/html expire_in: 1 mos script: - cd docs - doxygen - # If not building master branch, and there are Doxygen warnings, print them and bail out - - test -n $IS_PRIVATE && test $(cat doxygen-warning-log.txt | wc -l) -eq 0 || ( echo "Doxygen pass had some warnings:" && cat doxygen-warning-log.txt && false ) + # If there are Doxygen warnings, print them and bail out + - test $(cat doxygen-warning-log.txt | wc -l) -eq 0 || ( echo "Doxygen pass had some warnings:" && cat doxygen-warning-log.txt && false ) - make gh-linkcheck - make html + # If there are Sphinx warnings, print them and bail out + # Ignore warnings (sphinx-known-warnings.txt) already reported in: + # https://github.com/sphinx-doc/sphinx/issues/2683 + # https://github.com/sphinx-doc/sphinx/issues/4041 + # If a new warning has to be added, then it should be documented as above + # Note: this check is not clever enough to ignore the same warning + # but reported for different line of documentation. + # If s warning stays the same and the line number has changed, + # then update 'sphinx-known-warnings.txt' to reflect the new lines numbers. + - DIFF_FORMAT="--changed-group-format=%<%> --unchanged-group-format=" + - LOG_DIFF=$(diff $DIFF_FORMAT sphinx-known-warnings.txt sphinx-warning-log.txt) + - test -z "$LOG_DIFF" || ( echo "Sphinx pass had some new warnings:" && echo "$LOG_DIFF" && false ) test_nvs_on_host: stage: test diff --git a/docs/api-guides/build-system.rst b/docs/api-guides/build-system.rst index 34e35de3d..54660741e 100644 --- a/docs/api-guides/build-system.rst +++ b/docs/api-guides/build-system.rst @@ -358,7 +358,7 @@ Warning On Undefined Variables By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names. -If you don't want this behaviour, it can be disabled by disabling :ref:`CONFIG_MAKE_WARN_UNDEFINED_VARIABLES`. +If you don't want this behaviour, it can be disabled in menuconfig's top level menu under `SDK tool configuration`. Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles. diff --git a/docs/api-reference/peripherals/spi_master.rst b/docs/api-reference/peripherals/spi_master.rst index 89833e83d..e4b0347f8 100644 --- a/docs/api-reference/peripherals/spi_master.rst +++ b/docs/api-reference/peripherals/spi_master.rst @@ -66,6 +66,7 @@ In half duplex, the length of write phase and read phase are decided by ``trans_ ``trans_conf.rx_length`` respectively. ** Note that a half duplex transaction with both a read and write phase is not supported when using DMA. ** If such transaction is needed, you have to use one of the alternative solutions: + 1. use full-duplex mode instead. 2. disable the DMA by set the last parameter to 0 in bus initialization function just as belows: ``ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);`` @@ -109,8 +110,10 @@ Transaction data Normally, data to be transferred to or from a device will be read from or written to a chunk of memory indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure. When DMA is enabled for transfers, these buffers are highly recommended to meet the requirements as belows: + 1. allocated in DMA-capable memory using ``pvPortMallocCaps(size, MALLOC_CAP_DMA)``; 2. 32-bit aligned (start from the boundary and have length of multiples of 4 bytes). + If these requirements are not satisfied, efficiency of the transaction will suffer due to the allocation and memcpy of temporary buffers. diff --git a/docs/get-started/index.rst b/docs/get-started/index.rst index 16c8598df..31cda9cf3 100644 --- a/docs/get-started/index.rst +++ b/docs/get-started/index.rst @@ -207,7 +207,7 @@ Here are couple of tips on navigation and use of ``menuconfig``: .. note:: - Most ESP32 development boards have a 40MHz crystal installed. However, some boards use a 26MHz crystal. If your board uses a 26MHz crystal, or you get garbage output from serial port after code upload, adjust the :ref:`CONFIG_ESP32_XTAL_FREQ` option in menuconfig. + Most ESP32 development boards have a 40MHz crystal installed. However, some boards use a 26MHz crystal. If your board uses a 26MHz crystal, or you get garbage output from serial port after code upload, adjust the :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` option in menuconfig. .. _get-started-build-flash: diff --git a/docs/kconfiglib.py b/docs/kconfiglib.py index 9bc89f37e..566098d69 100644 --- a/docs/kconfiglib.py +++ b/docs/kconfiglib.py @@ -69,6 +69,7 @@ might add it in a safe way as a client API instead.""" import os import re import sys +import platform # File layout: # @@ -165,7 +166,8 @@ class Config(object): self.m = register_special_symbol(TRISTATE, "m", "m") self.y = register_special_symbol(TRISTATE, "y", "y") # DEFCONFIG_LIST uses this - register_special_symbol(STRING, "UNAME_RELEASE", os.uname()[2]) + # changed os.uname to platform.uname for compatibility with Windows + register_special_symbol(STRING, "UNAME_RELEASE", platform.uname()[2]) # The symbol with "option defconfig_list" set, containing a list of # default .config files diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt new file mode 100644 index 000000000..3981c7b9a --- /dev/null +++ b/docs/sphinx-known-warnings.txt @@ -0,0 +1,9 @@ +_build/inc/esp_a2dp_api.inc:26: WARNING: Invalid definition: Expected identifier in nested name. [error at 21] + union esp_a2d_mcc_t::@1 esp_a2d_mcc_t::cie + ---------------------^ +_build/inc/esp_bt_defs.inc:11: WARNING: Invalid definition: Expected identifier in nested name. [error at 21] + union esp_bt_uuid_t::@0 esp_bt_uuid_t::uuid + ---------------------^ +/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot). +/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot). +/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).