fix(docs): Fix links and versions (#11505)

* fix(docs): Fix links and versions

* fix(docs): Apply suggestions and leftover substitutions

Author: lucasssvaz

docs/conf_common.py

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

docs/en/contributing.rst

@@ -222,7 +222,7 @@ Documentation
 -------------
 
 If you are contributing to the documentation, please follow the instructions described in the
-`documentation guidelines <guides/docs_contributing>`_ to properly format and test your changes.
+`documentation guidelines <guides/docs_contributing.html>`_ to properly format and test your changes.
 
 Testing and CI
 --------------
@@ -435,7 +435,7 @@ Documentation Checks
 ^^^^^^^^^^^^^^^^^^^^
 
 The CI also checks the documentation for any compilation errors. This is important to ensure that the documentation layout is not broken.
-To build the documentation locally, please refer to the `documentation guidelines <guides/docs_contributing>`_.
+To build the documentation locally, please refer to the `documentation guidelines <guides/docs_contributing.html>`_.
 
 Code Style Checks
 ^^^^^^^^^^^^^^^^^

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 (3.0.X) 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
@@ -32,14 +32,16 @@ Installing using IDF Component Manager
 To add the Arduino component to your project using the IDF Component Manager, run the following command in your project directory:
 
 .. code-block:: bash
+    :substitutions:
 
-    idf.py add-dependency "espressif/arduino-esp32^3.0.2"
+    idf.py add-dependency "espressif/arduino-esp32^|version|"
 
 Or you can start a new project from a template with the Arduino component:
 
 .. code-block:: bash
+    :substitutions:
 
-    idf.py create-project-from-example "espressif/arduino-esp32^3.0.2:hello_world"
+    idf.py create-project-from-example "espressif/arduino-esp32^|version|:hello_world"
 
 Manual installation of Arduino framework
 ****************************************

docs/en/guides/docs_contributing.rst

@@ -49,11 +49,11 @@ 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.
+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::
 
-    pip install -U Sphinx
     pip install -r requirements.txt
 
 The requirements file is under the ``docs`` folder.
@@ -62,17 +62,14 @@ Using Visual Studio Code
 ************************
 
 If you are using the Visual Studio Code, you can install some extensions to help you while writing documentation.
+For reStructuredText, you can install the `reStructuredText Pack <https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext-pack>`_ extension.
 
-`reStructuredText Pack <https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext-pack>`_
-
-We also recommend you install to grammar check extension to help you to review English grammar.
-
-`Grammarly <https://marketplace.visualstudio.com/items?itemName=znck.grammarly>`_
+We also recommend you to install some grammar check extension to help you to review English grammar.
 
 Building
 ********
 
-To build the documentation and generate the HTML files, you can use the following command inside the ``docs`` folder. After a successful build, you can check the files inside the `_build/en/generic/html` folder.
+To build the documentation and generate the HTML files, you can use the following command inside the ``docs`` folder. After a successful build, you can check the files inside the ``_build/en/generic/html`` folder.
 
 .. code-block::
 

docs/en/index.rst

@@ -3,6 +3,7 @@ Welcome to ESP32 Arduino Core's documentation
 #############################################
 
 Here you will find all the relevant information about the project.
+This documentation is valid for the Arduino Core for ESP32 version |version| based on ESP-IDF |idf_version|.
 
 .. note::
    This is a work in progress documentation and we will appreciate your help! We are looking for contributors!

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.

docs/requirements.txt

@@ -1,5 +1,7 @@
+sphinx==4.5.0
 esp-docs>=1.4.0
 sphinx-copybutton==0.5.0
 sphinx-tabs==3.2.0
 numpydoc==1.5.0
 standard-imghdr==3.13.0
+Sphinx-Substitution-Extensions==2022.2.16