diff --git a/docs/conf_common.py b/docs/conf_common.py index 676cca899d5..6945c0d190d 100644 --- a/docs/conf_common.py +++ b/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", ] diff --git a/docs/en/contributing.rst b/docs/en/contributing.rst index 4ebe01cbf5b..7a7b99894eb 100644 --- a/docs/en/contributing.rst +++ b/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 `_ to properly format and test your changes. +`documentation guidelines `_ 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 `_. +To build the documentation locally, please refer to the `documentation guidelines `_. Code Style Checks ^^^^^^^^^^^^^^^^^ diff --git a/docs/en/esp-idf_component.rst b/docs/en/esp-idf_component.rst index f38dc44ec0c..13542cc3c87 100644 --- a/docs/en/esp-idf_component.rst +++ b/docs/en/esp-idf_component.rst @@ -14,9 +14,9 @@ For a simplified method, see `Installing using Boards Manager `_. -.. note:: Latest Arduino Core ESP32 version (3.0.X) is now compatible with `ESP-IDF 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 `_ 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 `_ 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 `_ 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 **************************************** diff --git a/docs/en/guides/docs_contributing.rst b/docs/en/guides/docs_contributing.rst index 20dc4c84cab..13f08c47618 100644 --- a/docs/en/guides/docs_contributing.rst +++ b/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 `_ extension. -`reStructuredText Pack `_ - -We also recommend you install to grammar check extension to help you to review English grammar. - -`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:: diff --git a/docs/en/index.rst b/docs/en/index.rst index 1314a8fc78d..89fc7e3bd6e 100644 --- a/docs/en/index.rst +++ b/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! diff --git a/docs/en/lib_builder.rst b/docs/en/lib_builder.rst index e7edb331fd3..a8126c18edc 100644 --- a/docs/en/lib_builder.rst +++ b/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. diff --git a/docs/requirements.txt b/docs/requirements.txt index d3017fb5adc..ef2ab88cb65 100644 --- a/docs/requirements.txt +++ b/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