fix(docs): Fix links and versions

Author: lucasssvaz

docs/conf_common.py

@@ -2,6 +2,12 @@
 
 from esp_docs.conf_docs import *  # noqa: F403,F401
 
+# Used by sphinx_substitution_extensions 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",
     "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,7 +14,7 @@ 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 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.
 
 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.
 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.
@@ -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 properly work with the documentation, 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/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