docs: document build arguments of the Docker image

docs/en/api-guides/tools/idf-docker-image.rst

@@ -59,7 +59,7 @@ The above command explained:
 
 To build with a specific docker image tag, specify it as ``espressif/idf:TAG``, for example::
 
-    docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.0 idf.py build
+    docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.4 idf.py build
 
 You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags.
 
@@ -100,3 +100,22 @@ Then inside the container, use ``idf.py`` as usual::
 .. note::
 
     Commands which communicate with the development board, such as ``idf.py flash`` and ``idf.py monitor`` will not work in the container unless the serial port is passed through into the container. However currently this is not possible with Docker for Windows (https://github.com/docker/for-win/issues/1018) and Docker for Mac (https://github.com/docker/for-mac/issues/900).
+
+Building custom images
+======================
+
+The Dockerfile in ESP-IDF repository provides several build arguments which can be used to customize the Docker image:
+
+- ``IDF_CLONE_URL``: URL of the repository to clone ESP-IDF from. Can be set to a custom URL when working with a fork of ESP-IDF. Default is ``https://github.com/espressif/esp-idf.git``.
+- ``IDF_CLONE_BRANCH_OR_TAG``: Name of a git branch or tag use when cloning ESP-IDF. This value is passed to ``git clone`` command using the ``--branch`` argument. Default is ``master``.
+- ``IDF_CHECKOUT_REF``: If this argument is set to a non-empty value, ``git checkout $IDF_CHECKOUT_REF`` command will be performed 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.
+- ``IDF_CLONE_SHALLOW``: If this argument is set to a non-empty value, ``--depth=1 --shallow-submodules`` arguments will be used when performing ``git clone``. This 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.
+- ``IDF_INSTALL_TARGETS``: Comma-separated list of IDF targets to install toolchains for, or ``all`` to install toolchains for all targets. Selecting specific targets reduces the amount of data downloaded and the size of the resulting Docker image. Default is ``all``.
+
+To use these arguments, pass them via the ``--build-arg`` command line option. For example, the following command will build a Docker image with a shallow clone of ESP-IDF v4.4.1 and tools for ESP32-C3, only::
+
+    docker build -t idf-custom:v4.4.1-esp32c3 \
+        --build-arg IDF_CLONE_BRANCH_OR_TAG=v4.4.1 \
+        --build-arg IDF_CLONE_SHALLOW=1 \
+        --build-arg IDF_INSTALL_TARGETS=esp32c3 \
+        tools/docker