tools/docker: add README.md file to be displayed on Docker Hub

Closes https://github.com/espressif/esp-idf/issues/7933

.github/workflows/docker.yml

@@ -73,3 +73,15 @@ jobs:
           build-args: |
             IDF_CLONE_URL=${{ github.server_url }}/${{ github.repository }}.git
             IDF_CLONE_BRANCH_OR_TAG=${{ env.CLONE_BRANCH_OR_TAG }}
+
+      - name: Update Docker Hub repository description (master branch)
+        if: ${{ github.ref_type == 'branch' && github.ref_name == 'master' }}
+        uses: peter-evans/dockerhub-description@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          # Token based authentication is not supported here:
+          # https://github.com/peter-evans/dockerhub-description/issues/10
+          # https://github.com/docker/roadmap/issues/115#issuecomment-891694974
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+          repository: ${{ env.DOCKERHUB_REPO }}
+          readme-filepath: ./tools/docker/README.md

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

@@ -2,6 +2,9 @@
 IDF Docker Image
 ****************
 
+..
+    When changing this page, please keep tools/docker/README.md in sync.
+
 .. highlight:: bash
 
 IDF Docker image (``espressif/idf``) is intended for building applications and libraries with specific versions of ESP-IDF, when doing automated builds.

tools/docker/README.md

@@ -0,0 +1,31 @@
+<!-- This is a brief version of docs/en/api-guides/tools/idf-docker-image.rst
+     intended to be displayed on the Docker Hub page: https://hub.docker.com/r/espressif/idf.
+     When changing this page, please keep idf-docker-image.rst in sync.
+     (Keep the differences between Markdown and restructuredText in mind.)
+ -->
+
+# ESP-IDF Docker Image
+
+This is a Docker image for the [Espressif IoT Development Framework (ESP-IDF)](https://github.com/espressif/esp-idf). It is intended for building applications and libraries with specific versions of ESP-IDF, when doing automated builds.
+
+This image contains a copy of ESP-IDF and all the tools necessary to build ESP-IDF projects.
+
+## Tags
+
+Multiple tags of this image are maintained:
+
+- `latest`: tracks `master` branch of ESP-IDF
+- `vX.Y`: corresponds to ESP-IDF release `vX.Y`
+- `release-vX.Y`: tracks `release/vX.Y` branch of ESP-IDF
+
+## Basic Usage
+
+Build a project located in the current directory using `idf.py build` command:
+
+```bash
+docker run --rm -v $PWD:/project -w /project espressif/idf:latest idf.py build
+```
+
+## Documentation
+
+For more information about this image and the detailed usage instructions, please refer to the ESP-IDF Programming Guide page: [IDF Docker Image](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-docker-image.html).