docs(lib-builder): Add docker image documentation

Author: lucasssvaz

.gitignore

@@ -50,3 +50,7 @@ libraries/Insights/examples/*/*.ino.zip
 !.vale/styles/Vocab/
 .vale/styles/Vocab/*
 !.vale/styles/Vocab/Espressif/
+
+# Ignore Lib Builder Docker run scripts
+/run.sh
+/run.ps1

docs/en/lib_builder.rst

@@ -152,8 +152,10 @@ This build command will build for the ESP32-S3 target. You can specify other tar
 
 * esp32
 * esp32s2
-* esp32c3
 * esp32s3
+* esp32c2
+* esp32c3
+* esp32h2
 
 Set Build Type
 ^^^^^^^^^^^^^^
@@ -169,11 +171,103 @@ Set the build type. ex. 'build' to build the project and prepare for uploading t
 Additional Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Specify additional configs to be applied. ex. 'qio 80m' to compile for QIO Flash@80MHz. Requires -b
+Specify additional configs to be applied. ex. 'qio 80m' to compile for QIO Flash@80MHz.
 
 .. note:: This command requires the ``-b`` to work properly.
 
 
 .. code-block:: bash
 
     ./build.sh -t esp32 -b idf_libs qio 80m
+
+Docker Image
+------------
+
+You can use a docker image that has all the dependencies installed to build the libraries. The image is based on Ubuntu 22.04 and contains:
+
+* Common utilities such as ``git``, ``wget`` and ``curl``;
+* Python 3.9 or newer;
+* A copy of a specific version of Lib Builder. See below for information about versions;
+* All dependencies required to build the libraries.
+
+Tags
+****
+
+Multiple tags of this image are maintained:
+
+- ``latest``: tracks ``master`` branch of the Lib Builder
+- ``vX.Y``: corresponds to Lib Builder release ``vX.Y``
+- ``release-vX.Y``: tracks ``release/vX.Y`` branch of the Lib Builder
+
+.. note::
+    Versions of Lib Builder released before this feature was introduced do not have corresponding Docker image versions.
+    You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/esp32-arduino-lib-builder/tags.
+
+Usage
+*****
+
+Before using the ``espressif/esp32-arduino-lib-builder`` Docker image locally, make sure you have Docker installed.
+Follow the instructions at https://docs.docker.com/install/, if it is not installed yet.
+
+If using the image in a CI environment, consult the documentation of your CI service on how to specify the image used for the build process.
+
+Building the Libraries
+^^^^^^^^^^^^^^^^^^^^^^
+
+You have two options to run the Docker image to build the libraries. Manually or using the provided run script.
+
+To run the Docker image manually, use the following command from the root of the ``arduino-esp32`` repository:
+
+.. code-block:: bash
+    docker run -it -v $PWD:/arduino-esp32 -e TERM=xterm-256color espressif/esp32-arduino-lib-builder
+
+This will start the Lib Builder UI for compiling the libraries. The above command explained:
+
+- ``docker run``: Runs a Docker image. It is a shorter form of the command ``docker container run``.
+- ``-it``: Allocates a pseudo-TTY and starts an interactive shell in the container.
+- ``-v $PWD:/project``: Mounts the current directory on the host (``$PWD``) as ``/arduino-esp32`` directory in the container.
+- ``-e TERM=xterm-256color``: Set the terminal type to ``xterm-256color``. This is required if you want the colors to be displayed correctly.
+- ``espressif/esp32-arduino-lib-builder``: uses Docker image ``espressif/esp32-arduino-lib-builder`` with tag ``latest``. The ``latest`` tag is implicitly added by Docker when no tag is specified.
+
+To run the Docker image using the provided run script it 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:
+
+.. code-block:: bash
+
+    curl -LJO https://raw.githubusercontent.com/espressif/esp32-arduino-lib-builder/master/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
+
+    Invoke-WebRequest -Uri "https://raw.githubusercontent.com/espressif/esp32-arduino-lib-builder/master/tools/docker/run.ps1" -OutFile "run.ps1"
+    .\run.ps1 $PWD
+
+.. warning::
+    It is always a good practice to understand what the script does before running it.
+    Make sure to analyze the content of the script to ensure it is safe to run and won't cause any harm to your system.
+
+Building Custom Images
+**********************
+
+To build a custom Docker image, you need to clone the Lib Builder repository and use the provided Dockerfile in the Lib Builder repository. The Dockerfile is located in the ``tools/docker`` directory.
+
+The `Docker file in the Lib Builder repository <https://github.com/espressif/esp32-arduino-lib-builder/blob/master/tools/docker/Dockerfile>`_ provides several build arguments which can be used to customize the Docker image:
+
+- ``LIBBUILDER_CLONE_URL``: URL of the repository to clone Lib Builder from. Can be set to a custom URL when working with a fork of Lib Builder. The default is ``https://github.com/espressif/esp32-arduino-lib-builder.git``;
+- ``LIBBUILDER_CLONE_BRANCH_OR_TAG``: Name of a git branch or tag used when cloning Lib Builder. This value is passed to the ``git clone`` command using the ``--branch`` argument. The default is ``master``;
+- ``LIBBUILDER_CHECKOUT_REF``: If this argument is set to a non-empty value, ``git checkout $LIBBUILDER_CHECKOUT_REF`` command performs after cloning. This argument can be set to the SHA of the specific commit to check out, for example, if some specific commit on a release branch is desired;
+- ``LIBBUILDER_CLONE_SHALLOW``: If this argument is set to a non-empty value, ``--depth=1 --shallow-submodules`` arguments are used when performing ``git clone``. Depth can be customized using ``LIBBUILDER_CLONE_SHALLOW_DEPTH``. Doing a shallow clone significantly reduces the amount of data downloaded and the size of the resulting Docker image. However, if switching to a different branch in such a "shallow" repository is necessary, an additional ``git fetch origin <branch>`` command must be executed first;
+- ``LIBBUILDER_CLONE_SHALLOW_DEPTH``: This argument specifies the depth value to use when doing a shallow clone. If not set, ``--depth=1`` will be used. This argument has effect only if ``LIBBUILDER_CLONE_SHALLOW`` is used. Use this argument if you are building a Docker image for a branch, and the image has to contain the latest tag on that branch. To determine the required depth, run ``git describe`` for the given branch and note the offset number. Increment it by 1, then use it as the value of this argument. The resulting image will contain the latest tag on the branch, and consequently ``git describe`` command inside the Docker image will work as expected;
+
+To use these arguments, pass them via the ``--build-arg`` command line option. For example, the following command builds a Docker image with a shallow clone of Lib Builder from a specific repository and branch:
+
+.. code-block:: bash
+
+    docker buildx build -t lib-builder-custom:master \
+        --build-arg LIBBUILDER_CLONE_BRANCH_OR_TAG=master \
+        --build-arg LIBBUILDER_CLONE_SHALLOW=1 \
+        --build-arg LIBBUILDER_CLONE_URL=https://github.com/espressif/esp32-arduino-lib-builder \
+        tools/docker