From 3a23146518cf9e179401a73cd315ebf4f69d6cd1 Mon Sep 17 00:00:00 2001 From: Marek Fiala Date: Mon, 5 Jan 2026 16:20:42 +0100 Subject: [PATCH 1/3] docs(tools): Updated argument via file with quotations Closes https://github.com/espressif/esp-idf/issues/18077 --- docs/en/api-guides/tools/idf-py.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/api-guides/tools/idf-py.rst b/docs/en/api-guides/tools/idf-py.rst index 06da469598..9a0ac5726d 100644 --- a/docs/en/api-guides/tools/idf-py.rst +++ b/docs/en/api-guides/tools/idf-py.rst @@ -401,9 +401,9 @@ For example, let's have a file `custom_flash.txt`: flash --baud 115200 -Then the command can be executed as: ``idf.py @custom_flash.txt monitor`` +Then the command can be executed as: ``idf.py "@custom_flash.txt" monitor`` -Arguments from a file can be combined with additional command line arguments, and multiple files annotated with ``@`` can be used simultaneously. For instance, if there is a second file ``another_config.txt``, both can be utilized by specifying ``idf.py @custom_flash.txt @another_config.txt monitor``. +Arguments from a file can be combined with additional command line arguments, and multiple files annotated with ``@`` can be used simultaneously. For instance, if there is a second file ``another_config.txt``, both can be utilized by specifying ``idf.py "@custom_flash.txt" "@another_config.txt" monitor``. A further example of how this argument file can be used, e.g., creating configuration profile files via @filename, is in the :example_file:`Multiple Build Configurations Example `. From 9b0475de347d2c05250459cf2e93119691e4c0de Mon Sep 17 00:00:00 2001 From: Marek Fiala Date: Mon, 5 Jan 2026 16:24:59 +0100 Subject: [PATCH 2/3] docs(tools): Made static link for config profile files Made the reference link to v5.5 to reflect the correct example, as in later version the example was changed. --- docs/en/api-guides/tools/idf-py.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/api-guides/tools/idf-py.rst b/docs/en/api-guides/tools/idf-py.rst index 9a0ac5726d..9a55f6608a 100644 --- a/docs/en/api-guides/tools/idf-py.rst +++ b/docs/en/api-guides/tools/idf-py.rst @@ -405,7 +405,7 @@ Then the command can be executed as: ``idf.py "@custom_flash.txt" monitor`` Arguments from a file can be combined with additional command line arguments, and multiple files annotated with ``@`` can be used simultaneously. For instance, if there is a second file ``another_config.txt``, both can be utilized by specifying ``idf.py "@custom_flash.txt" "@another_config.txt" monitor``. -A further example of how this argument file can be used, e.g., creating configuration profile files via @filename, is in the :example_file:`Multiple Build Configurations Example `. +A further example of how this argument file can be used, e.g., creating configuration profile files via @filename, is in the `Create configuration profile files `_ paragraph in Multiple Build Configurations Example. Extending ``idf.py`` ==================== @@ -517,3 +517,4 @@ Basic Usage Examples .. _CCache: https://ccache.dev/ .. _click context: https://click.palletsprojects.com/en/stable/api/#context .. _CMake presets: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html +.. _profile_file: https://github.com/espressif/esp-idf/tree/release/v5.5/examples/build_system/cmake/multi_config#create-configuration-profile-files-via-filename From b48cb1c5a9f15131ce0b22a44551d716a1d86e33 Mon Sep 17 00:00:00 2001 From: Shen Mengjing Date: Fri, 9 Jan 2026 10:42:40 +0800 Subject: [PATCH 3/3] docs: Update CN translation for idf-py.rst --- docs/zh_CN/api-guides/tools/idf-py.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/zh_CN/api-guides/tools/idf-py.rst b/docs/zh_CN/api-guides/tools/idf-py.rst index be90fde7b8..14d7800afb 100644 --- a/docs/zh_CN/api-guides/tools/idf-py.rst +++ b/docs/zh_CN/api-guides/tools/idf-py.rst @@ -401,11 +401,11 @@ ESP-IDF 支持 `CMake presets`_ 以简化多个构建配置的管理。此功能 flash --baud 115200 -运行命令：``idf.py @custom_flash.txt monitor`` +运行命令：``idf.py "@custom_flash.txt" monitor`` -文件中的参数可以与额外的命令行参数结合使用，也支持同时使用带有 ``@`` 标注的多个文件。例如，另有一个文件 ``another_config.txt``，此时，可以通过指定 ``idf.py @custom_flash.txt @another_config.txt monitor`` 同时使用两个文件。 +文件中的参数可以与额外的命令行参数结合使用，也支持同时使用带有 ``@`` 标注的多个文件。例如，另有一个文件 ``another_config.txt``，此时，可以通过指定 ``idf.py "@custom_flash.txt" "@another_config.txt" monitor`` 同时使用两个文件。 -关于参数文件的更多示例，如通过 @filename 创建配置文件概要，请参阅 :example_file:`多个构建配置示例 `。 +关于参数文件的更多示例，如通过 @filename 创建配置文件概要，请参阅多个构建配置示例文档中的 `创建配置文件概要 `_ 小节。 扩展 ``idf.py`` ==================== @@ -517,3 +517,4 @@ ESP-IDF 支持 `CMake presets`_ 以简化多个构建配置的管理。此功能 .. _CCache: https://ccache.dev/ .. _click context: https://click.palletsprojects.com/en/stable/api/#context .. _CMake presets: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html +.. _profile_file: https://github.com/espressif/esp-idf/tree/release/v5.5/examples/build_system/cmake/multi_config#create-configuration-profile-files-via-filename