From 7d9aff3913a04c76b59a97615070ba8e41a2f1b7 Mon Sep 17 00:00:00 2001
From: Ivan Grokhotkov <ivan@espressif.com>
Date: Thu, 26 May 2022 01:10:04 +0200
Subject: [PATCH] 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                  | 12 +++++++
 docs/en/api-guides/tools/idf-docker-image.rst |  3 ++
 tools/docker/README.md                        | 31 +++++++++++++++++++
 3 files changed, 46 insertions(+)
 create mode 100644 tools/docker/README.md

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index d1ee4a8d73..9a9afbcd44 100644
--- a/.github/workflows/docker.yml
+++ b/.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
diff --git a/docs/en/api-guides/tools/idf-docker-image.rst b/docs/en/api-guides/tools/idf-docker-image.rst
index 8b104f8b59..7ddb2eb4e4 100644
--- a/docs/en/api-guides/tools/idf-docker-image.rst
+++ b/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.
diff --git a/tools/docker/README.md b/tools/docker/README.md
new file mode 100644
index 0000000000..e5e12bd88b
--- /dev/null
+++ b/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).