From e5410450beccc2409592f5464ebf306796a8994b Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 20 Mar 2020 19:07:09 +1100 Subject: [PATCH 1/2] docs: Fix the secure-boot page redirect --- docs/page_redirects.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index f46f814f6f..8e9d88d3db 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -53,4 +53,4 @@ api-guide/unit-tests-cmake api-guide/unit-tests api-reference/network/tcpip_adapter api-reference/network/esp_netif # The 'secure boot' guides are now 'secure boot v1' guides -security/secure-boot.rst security/secure-boot-v1.rst +security/secure-boot security/secure-boot-v1 From 5fbf95d691ff9454e010c35b40d4d6b7cb83a81f Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 20 Mar 2020 19:52:38 +1100 Subject: [PATCH 2/2] docs: Expand the description of per-target custom macro directives --- docs/en/contribute/documenting-code.rst | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index 6721611ca6..62b121874e 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -320,11 +320,28 @@ Substitution macros """"""""""""""""""" When you need to refer to the chip's name, toolchain name, path or other common names that depend on the target type you can consider using the substitution macros supplied by :idf_file:`docs/idf_extensions/format_idf_target.py`. -This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will render as: This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`. +For example, the following reStructuredText content: -This extension also supports markup for defining a local (for a single .rst-file) substitutions. You can do this by putting a definition like {\IDF_TARGET_SUFFIX:default="DEFAULT_VALUE",esp32="ESP32_VALUE",esp32s2beta="ESP32S2BETA_VALUE"}, in your rst-file. This will define a target-dependent substitution of the tag {\IDF_TARGET_SUFFIX} in the current rst-file. For example: + This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` + +Would render in the documentation as: + + This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`. + +This extension also supports markup for defining local (within a single source file) substitutions. Place a definition like the following into a single line of the RST file: + + {\IDF_TARGET_SUFFIX:default="DEFAULT_VALUE", esp32="ESP32_VALUE", esp32s2="ESP32S2_VALUE"} + +This will define a target-dependent substitution of the tag {\IDF_TARGET_SUFFIX} in the current RST file. For example: + + {\IDF_TARGET_TX_PIN:default="IO3", esp32="IO4", esp32s2="IO5"} + +Will define a substitution for the tag {\IDF_TARGET_TX_PIN}, which would be replaced by the text IO5 if sphinx was called with the tag esp32s2. + +.. note:: + + These single-file definitions can be placed anywhere in the .rst file (on their own line), but the name of the directive must start with ``IDF_TARGET_``. -{\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2beta="IO5"} will define a substitution for the tag {\IDF_TARGET_TX_PIN}, which would be replaced by the text IO5 if sphinx was called with the tag esp32s2beta. Put it all together -------------------