fix(docs): Apply suggestions and leftover substitutions

Author: lucasssvaz

docs/conf_common.py

@@ -2,7 +2,7 @@
 
 from esp_docs.conf_docs import *  # noqa: F403,F401
 
-# Used by sphinx_substitution_extensions for substituting variables in the documentation
+# Used for substituting variables in the documentation
 rst_prolog = """
 .. |version| replace:: 3.2.0
 .. |idf_version| replace:: 5.4
@@ -33,7 +33,7 @@
 extensions += [  # noqa: F405
     "sphinx_copybutton",
     "sphinx_tabs.tabs",
-    "sphinx_substitution_extensions",
+    "sphinx_substitution_extensions",  # For allowing substitutions inside code blocks
     "esp_docs.esp_extensions.dummy_build_system",
 ]
 

docs/en/esp-idf_component.rst

@@ -14,9 +14,9 @@ For a simplified method, see `Installing using Boards Manager <https://docs.espr
 If you plan to use these modified settings multiple times, for different projects and targets, you can recompile the Arduino core with the new settings using the Arduino Static Library Builder.
 For more information, see the `Lib Builder documentation <lib_builder.html>`_.
 
-.. note:: Latest Arduino Core ESP32 version (|version|) is now compatible with `ESP-IDF v5.1 <https://github.com/espressif/esp-idf/tree/release/v5.1>`_. Please consider this compatibility when using Arduino as a component in ESP-IDF.
+.. note:: Latest Arduino Core ESP32 version (|version|) is now compatible with ESP-IDF v\ |idf_version|\ . Please consider this compatibility when using Arduino as a component in ESP-IDF.
 
-For easiest use of Arduino framework as a ESP-IDF component, you can use the `IDF Component Manager <https://docs.espressif.com/projects/esp-idf/en/v5.1.4/esp32/api-guides/tools/idf-component-manager.html>`_ to add the Arduino component to your project.
+For easiest use of Arduino framework as a ESP-IDF component, you can use the `IDF Component Manager <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html>`_ to add the Arduino component to your project.
 This will automatically clone the repository and its submodules. You can find the Arduino component in the `ESP Registry <https://components.espressif.com/components/espressif/arduino-esp32>`_ together with dependencies list and examples.
 
 Installation

docs/en/guides/docs_contributing.rst

@@ -49,7 +49,7 @@ Before starting your collaboration, you need to get the documentation source cod
 Requirements
 ************
 
-To properly work with the documentation, you need to install some packages in your system. Note that depending on
+To build the documentation properly, you need to install some packages in your system. Note that depending on
 your system, you may need to use a virtual environment to install the packages.
 
 .. code-block::

docs/en/lib_builder.rst

@@ -293,8 +293,9 @@ You have two options to run the Docker image to build the libraries. Manually or
 To run the Docker image manually, use the following command from the root of the ``arduino-esp32`` repository:
 
 .. code-block:: bash
+    :substitutions:
 
-    docker run --rm -it -v $PWD:/arduino-esp32 -e TERM=xterm-256color espressif/esp32-arduino-lib-builder:release-v5.1
+    docker run --rm -it -v $PWD:/arduino-esp32 -e TERM=xterm-256color espressif/esp32-arduino-lib-builder:release-v|idf_version|
 
 This will start the Lib Builder UI for compiling the libraries. The above command explained:
 
@@ -304,7 +305,7 @@ This will start the Lib Builder UI for compiling the libraries. The above comman
 - ``-t`` Allocate a pseudo-TTY;
 - ``-e TERM=xterm-256color``: Optional. Sets the terminal type to ``xterm-256color`` to display colors correctly;
 - ``-v $PWD:/arduino-esp32``: Optional. Mounts the current folder at ``/arduino-esp32`` inside the container. If not provided, the container will not copy the compiled libraries to the host machine;
-- ``espressif/esp32-arduino-lib-builder:release-v5.1``: uses Docker image ``espressif/esp32-arduino-lib-builder`` with tag ``release-v5.1``.
+- :substitution-code:`espressif/esp32-arduino-lib-builder:release-v|idf_version|`: uses Docker image ``espressif/esp32-arduino-lib-builder`` with tag :substitution-code:`release-v|idf_version|`.
   The ``latest`` tag is implicitly added by Docker when no tag is specified. It is recommended to use a specific version tag to ensure reproducibility of the build process.
 
 .. warning::
@@ -324,24 +325,27 @@ By default the docker container will run the user interface script. If you want
 For example, to run a terminal inside the container, you can run:
 
 .. code-block:: bash
+    :substitutions:
 
-    docker run -it espressif/esp32-arduino-lib-builder:release-v5.1 /bin/bash
+    docker run -it espressif/esp32-arduino-lib-builder:release-v|idf_version| /bin/bash
 
 Running the Docker image using the provided run script will depend on the host OS.
 Use the following command from the root of the ``arduino-esp32`` repository to execute the image in a Linux or macOS environment for
-the ``release-v5.1`` tag:
+the :substitution-code:`release-v|idf_version|` tag:
 
 .. code-block:: bash
+    :substitutions:
 
-    curl -LJO https://raw.githubusercontent.com/espressif/esp32-arduino-lib-builder/refs/heads/release/v5.1/tools/docker/run.sh
+    curl -LJO https://raw.githubusercontent.com/espressif/esp32-arduino-lib-builder/refs/heads/release/v|idf_version|/tools/docker/run.sh
     chmod +x run.sh
     ./run.sh $PWD
 
 For Windows, use the following command in PowerShell from the root of the ``arduino-esp32`` repository:
 
 .. code-block:: powershell
+    :substitutions:
 
-    Invoke-WebRequest -Uri "https://raw.githubusercontent.com/espressif/esp32-arduino-lib-builder/refs/heads/release/v5.1/tools/docker/run.ps1" -OutFile "run.ps1"
+    Invoke-WebRequest -Uri "https://raw.githubusercontent.com/espressif/esp32-arduino-lib-builder/refs/heads/release/v|idf_version|/tools/docker/run.ps1" -OutFile "run.ps1"
     .\run.ps1 $pwd
 
 As the script is unsigned, you may need to change the execution policy of the current session before running the script.