From cd028e5efa5250ab3404644d8b421885848394e0 Mon Sep 17 00:00:00 2001
From: Lidi Zheng <lidiz@google.com>
Date: Mon, 24 Aug 2020 14:44:34 -0700
Subject: [PATCH 1/5] Add a script to generate all languages doc and push to
 GitHub

---
 tools/distrib/docgen/_generate_python_doc.sh |  30 +++++
 tools/distrib/docgen/all_lang_docgen.sh      | 116 +++++++++++++++++++
 2 files changed, 146 insertions(+)
 create mode 100755 tools/distrib/docgen/_generate_python_doc.sh
 create mode 100755 tools/distrib/docgen/all_lang_docgen.sh

diff --git a/tools/distrib/docgen/_generate_python_doc.sh b/tools/distrib/docgen/_generate_python_doc.sh
new file mode 100755
index 00000000000..d5386ff9ec9
--- /dev/null
+++ b/tools/distrib/docgen/_generate_python_doc.sh
@@ -0,0 +1,30 @@
+#! /bin/bash
+# Copyright 2020 The gRPC Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This script is meant to be ran in Docker instance of python:3.8.
+
+set -ex
+
+# Some Python package installation requires permission to change homedir. But
+# due to the user-override in all_lang_docgen.sh, the user in the container
+# doesn't have a home dir which leads to permission denied error.
+export HOME="/tmp/$(id -u)"
+mkdir -p "${HOME}"
+
+pip install -r requirements.bazel.txt
+tools/run_tests/run_tests.py -c opt -l python --compiler python3.8 --newline_on_success -j 8 --build_only
+source py38_native/bin/activate
+pip install --upgrade Sphinx
+python setup.py doc
diff --git a/tools/distrib/docgen/all_lang_docgen.sh b/tools/distrib/docgen/all_lang_docgen.sh
new file mode 100755
index 00000000000..ab67c7f301d
--- /dev/null
+++ b/tools/distrib/docgen/all_lang_docgen.sh
@@ -0,0 +1,116 @@
+#! /bin/bash
+# Copyright 2020 The gRPC Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# A script to automatically generate API references and push to GitHub.
+# This script covers Core/C++/ObjC/C#/PHP/Python. Due to lack of tooling for
+# Cython, Python document generation unfortunately needs to compile everything.
+# So, this script will take couple minutes to run.
+#
+# Generate and push:
+#
+#     tools/distrib/docgen/all_lang-docgen.sh YOUR_GITHUB_USERNAME
+#
+# Just generate:
+#
+#     tools/distrib/docgen/all_lang-docgen.sh
+#
+
+set -e
+
+# Find out the gRPC version and print it
+GRPC_VERSION="$(cat build_handwritten.yaml | grep -m1 -Eo ' version: .*' | grep -Eo '[0-9].*')"
+echo "Generating documents for version ${GRPC_VERSION}..."
+
+# Specifies your GitHub user name or generates documents locally
+if [ $# -eq 0 ]; then
+    read -r -p "- Are you sure to generate documents without push to GitHub? [y/N] " response
+    if [[ "$response" =~ ^([yY][eE][sS]|[yY])$ ]]; then
+        GITHUB_USER=''
+    else
+        echo "Generation stopped"
+        exit 1
+    fi
+else
+    if [ $# -eq 1 ]; then
+        GITHUB_USER=$1
+    else
+        echo "Too many arguments!"
+        exit 1
+    fi
+fi
+
+# Exits on pending changes; please double check for unwanted code changes
+git diff --exit-code
+git submodule update --init --recursive
+
+# Changes to project root
+dir=$(dirname "${0}")
+cd "${dir}/../../.."
+
+# Clones the API reference GitHub Pages branch
+PAGES_PATH="/tmp/gh-pages"
+rm -rf "${PAGES_PATH}"
+git clone https://github.com/grpc/grpc -b gh-pages "${PAGES_PATH}"
+
+# Generates Core / C++ / ObjC / PHP documents
+rm -rf "${PAGES_PATH}/core" "${PAGES_PATH}/cpp" "${PAGES_PATH}/objc" "${PAGES_PATH}/php"
+docker run --rm -it \
+    -v "$(pwd)":/work/grpc \
+    --user "$(id -u):$(id -g)" \
+    hrektts/doxygen /work/grpc/tools/doxygen/run_doxygen.sh
+mv doc/ref/c++/html "${PAGES_PATH}/cpp"
+mv doc/ref/core/html "${PAGES_PATH}/core"
+mv doc/ref/objc/html "${PAGES_PATH}/objc"
+mv doc/ref/php/html "${PAGES_PATH}/php"
+
+# Generates C# documents
+rm -rf "${PAGES_PATH}/csharp"
+docker run --rm -it \
+    -v "$(pwd)":/work \
+    -w /work/src/csharp/docfx \
+    --user "$(id -u):$(id -g)" \
+    tsgkadot/docker-docfx:latest docfx
+mv src/csharp/docfx/html "${PAGES_PATH}/csharp"
+
+# Generates Python documents
+rm -rf "${PAGES_PATH}/python"
+docker run --rm -it \
+    -v "$(pwd)":/work \
+    -w /work \
+    --user "$(id -u):$(id -g)" \
+    python:3.8 tools/distrib/docgen/_generate_python_doc.sh
+mv doc/build "${PAGES_PATH}/python"
+
+# At this point, document generation is finished.
+echo "================================================================="
+echo "  Successfully generated documents for version ${GRPC_VERSION}."
+echo "================================================================="
+
+# Uploads to GitHub
+if [[ ! -z "${GITHUB_USER}" ]]; then
+    BRANCH_NAME="doc-${GRPC_VERSION}"
+
+    cd "${PAGES_PATH}"
+    git remote add "${GITHUB_USER}" "git@github.com:${GITHUB_USER}/grpc.git"
+    git checkout -b "${BRANCH_NAME}"
+    git add --all
+    git commit -m "Auto-update documentation for gRPC ${GRPC_VERSION}"
+    git push --set-upstream "${GITHUB_USER}" "${BRANCH_NAME}"
+    cd -
+
+    echo "Please check https://github.com/${GITHUB_USER}/grpc/tree/${BRANCH_NAME} for generated documents."
+else
+    echo "Please check ${PAGES_PATH} for generated documents."
+fi

From 4f5f082deeb0540b5ee88c436d63f0ff0c5f0847 Mon Sep 17 00:00:00 2001
From: Lidi Zheng <lidiz@google.com>
Date: Mon, 24 Aug 2020 17:17:52 -0700
Subject: [PATCH 2/5] Make shellcheck happy

---
 tools/distrib/docgen/_generate_python_doc.sh | 4 +++-
 tools/distrib/docgen/all_lang_docgen.sh      | 6 +++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/tools/distrib/docgen/_generate_python_doc.sh b/tools/distrib/docgen/_generate_python_doc.sh
index d5386ff9ec9..a909ca0401f 100755
--- a/tools/distrib/docgen/_generate_python_doc.sh
+++ b/tools/distrib/docgen/_generate_python_doc.sh
@@ -20,11 +20,13 @@ set -ex
 # Some Python package installation requires permission to change homedir. But
 # due to the user-override in all_lang_docgen.sh, the user in the container
 # doesn't have a home dir which leads to permission denied error.
-export HOME="/tmp/$(id -u)"
+HOME="/tmp/$(id -u)"
+export HOME
 mkdir -p "${HOME}"
 
 pip install -r requirements.bazel.txt
 tools/run_tests/run_tests.py -c opt -l python --compiler python3.8 --newline_on_success -j 8 --build_only
+# shellcheck disable=SC1091
 source py38_native/bin/activate
 pip install --upgrade Sphinx
 python setup.py doc
diff --git a/tools/distrib/docgen/all_lang_docgen.sh b/tools/distrib/docgen/all_lang_docgen.sh
index ab67c7f301d..877bde14600 100755
--- a/tools/distrib/docgen/all_lang_docgen.sh
+++ b/tools/distrib/docgen/all_lang_docgen.sh
@@ -30,13 +30,13 @@
 set -e
 
 # Find out the gRPC version and print it
-GRPC_VERSION="$(cat build_handwritten.yaml | grep -m1 -Eo ' version: .*' | grep -Eo '[0-9].*')"
+GRPC_VERSION="$(grep -m1 -Eo ' version: .*' build_handwritten.yaml | grep -Eo '[0-9].*')"
 echo "Generating documents for version ${GRPC_VERSION}..."
 
 # Specifies your GitHub user name or generates documents locally
 if [ $# -eq 0 ]; then
     read -r -p "- Are you sure to generate documents without push to GitHub? [y/N] " response
-    if [[ "$response" =~ ^([yY][eE][sS]|[yY])$ ]]; then
+    if [[ "${response[0]}" =~ ^([yY][eE][sS]|[yY])$ ]]; then
         GITHUB_USER=''
     else
         echo "Generation stopped"
@@ -99,7 +99,7 @@ echo "  Successfully generated documents for version ${GRPC_VERSION}."
 echo "================================================================="
 
 # Uploads to GitHub
-if [[ ! -z "${GITHUB_USER}" ]]; then
+if [[ -n "${GITHUB_USER}" ]]; then
     BRANCH_NAME="doc-${GRPC_VERSION}"
 
     cd "${PAGES_PATH}"

From e07297c7b16a61e0a0bb0bdf7db679a3da264ca0 Mon Sep 17 00:00:00 2001
From: Lidi Zheng <lidiz@google.com>
Date: Mon, 24 Aug 2020 17:28:46 -0700
Subject: [PATCH 3/5] Add a link to automatically create a PR

---
 tools/distrib/docgen/all_lang_docgen.sh | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tools/distrib/docgen/all_lang_docgen.sh b/tools/distrib/docgen/all_lang_docgen.sh
index 877bde14600..c32d48d9e14 100755
--- a/tools/distrib/docgen/all_lang_docgen.sh
+++ b/tools/distrib/docgen/all_lang_docgen.sh
@@ -111,6 +111,7 @@ if [[ -n "${GITHUB_USER}" ]]; then
     cd -
 
     echo "Please check https://github.com/${GITHUB_USER}/grpc/tree/${BRANCH_NAME} for generated documents."
+    echo "Click https://github.com/grpc/grpc/compare/gh-pages...${GITHUB_USER}:${BRANCH_NAME} to create a PR."
 else
     echo "Please check ${PAGES_PATH} for generated documents."
 fi

From db9987a3d1c1414067316bf28427b699cd571230 Mon Sep 17 00:00:00 2001
From: Lidi Zheng <lidiz@google.com>
Date: Tue, 25 Aug 2020 13:07:46 -0700
Subject: [PATCH 4/5] Resolve comments

---
 tools/distrib/docgen/_generate_python_doc.sh |  3 +--
 tools/distrib/docgen/all_lang_docgen.sh      | 20 ++++++++++----------
 2 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/tools/distrib/docgen/_generate_python_doc.sh b/tools/distrib/docgen/_generate_python_doc.sh
index a909ca0401f..febc3188aed 100755
--- a/tools/distrib/docgen/_generate_python_doc.sh
+++ b/tools/distrib/docgen/_generate_python_doc.sh
@@ -20,9 +20,8 @@ set -ex
 # Some Python package installation requires permission to change homedir. But
 # due to the user-override in all_lang_docgen.sh, the user in the container
 # doesn't have a home dir which leads to permission denied error.
-HOME="/tmp/$(id -u)"
+HOME="$(mktemp -d)"
 export HOME
-mkdir -p "${HOME}"
 
 pip install -r requirements.bazel.txt
 tools/run_tests/run_tests.py -c opt -l python --compiler python3.8 --newline_on_success -j 8 --build_only
diff --git a/tools/distrib/docgen/all_lang_docgen.sh b/tools/distrib/docgen/all_lang_docgen.sh
index c32d48d9e14..cb9848a23da 100755
--- a/tools/distrib/docgen/all_lang_docgen.sh
+++ b/tools/distrib/docgen/all_lang_docgen.sh
@@ -30,12 +30,12 @@
 set -e
 
 # Find out the gRPC version and print it
-GRPC_VERSION="$(grep -m1 -Eo ' version: .*' build_handwritten.yaml | grep -Eo '[0-9].*')"
+GRPC_VERSION="$(grep -m1 -Eo ' version: .*' build_handwritten.yaml | grep -Eo '[0-9][^ ]*')"
 echo "Generating documents for version ${GRPC_VERSION}..."
 
 # Specifies your GitHub user name or generates documents locally
 if [ $# -eq 0 ]; then
-    read -r -p "- Are you sure to generate documents without push to GitHub? [y/N] " response
+    read -r -p "- Are you sure to generate documents without pushing to GitHub? [y/N] " response
     if [[ "${response[0]}" =~ ^([yY][eE][sS]|[yY])$ ]]; then
         GITHUB_USER=''
     else
@@ -62,7 +62,7 @@ cd "${dir}/../../.."
 # Clones the API reference GitHub Pages branch
 PAGES_PATH="/tmp/gh-pages"
 rm -rf "${PAGES_PATH}"
-git clone https://github.com/grpc/grpc -b gh-pages "${PAGES_PATH}"
+git clone --depth 1 https://github.com/grpc/grpc -b gh-pages "${PAGES_PATH}"
 
 # Generates Core / C++ / ObjC / PHP documents
 rm -rf "${PAGES_PATH}/core" "${PAGES_PATH}/cpp" "${PAGES_PATH}/objc" "${PAGES_PATH}/php"
@@ -102,13 +102,13 @@ echo "================================================================="
 if [[ -n "${GITHUB_USER}" ]]; then
     BRANCH_NAME="doc-${GRPC_VERSION}"
 
-    cd "${PAGES_PATH}"
-    git remote add "${GITHUB_USER}" "git@github.com:${GITHUB_USER}/grpc.git"
-    git checkout -b "${BRANCH_NAME}"
-    git add --all
-    git commit -m "Auto-update documentation for gRPC ${GRPC_VERSION}"
-    git push --set-upstream "${GITHUB_USER}" "${BRANCH_NAME}"
-    cd -
+    (cd "${PAGES_PATH}"
+        git remote add "${GITHUB_USER}" "git@github.com:${GITHUB_USER}/grpc.git"
+        git checkout -b "${BRANCH_NAME}"
+        git add --all
+        git commit -m "Auto-update documentation for gRPC ${GRPC_VERSION}"
+        git push --set-upstream "${GITHUB_USER}" "${BRANCH_NAME}"
+    )
 
     echo "Please check https://github.com/${GITHUB_USER}/grpc/tree/${BRANCH_NAME} for generated documents."
     echo "Click https://github.com/grpc/grpc/compare/gh-pages...${GITHUB_USER}:${BRANCH_NAME} to create a PR."

From 72a005981bbf724a7346b334087cf0be51e00d63 Mon Sep 17 00:00:00 2001
From: Lidi Zheng <lidiz@google.com>
Date: Tue, 25 Aug 2020 13:21:31 -0700
Subject: [PATCH 5/5] Shallow update not allowed (--depth)

---
 tools/distrib/docgen/all_lang_docgen.sh | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tools/distrib/docgen/all_lang_docgen.sh b/tools/distrib/docgen/all_lang_docgen.sh
index cb9848a23da..1eb1cd7486e 100755
--- a/tools/distrib/docgen/all_lang_docgen.sh
+++ b/tools/distrib/docgen/all_lang_docgen.sh
@@ -62,10 +62,11 @@ cd "${dir}/../../.."
 # Clones the API reference GitHub Pages branch
 PAGES_PATH="/tmp/gh-pages"
 rm -rf "${PAGES_PATH}"
-git clone --depth 1 https://github.com/grpc/grpc -b gh-pages "${PAGES_PATH}"
+git clone --single-branch https://github.com/grpc/grpc -b gh-pages "${PAGES_PATH}"
 
 # Generates Core / C++ / ObjC / PHP documents
 rm -rf "${PAGES_PATH}/core" "${PAGES_PATH}/cpp" "${PAGES_PATH}/objc" "${PAGES_PATH}/php"
+echo "Generating Core / C++ / ObjC / PHP documents in Docker..."
 docker run --rm -it \
     -v "$(pwd)":/work/grpc \
     --user "$(id -u):$(id -g)" \
@@ -77,6 +78,7 @@ mv doc/ref/php/html "${PAGES_PATH}/php"
 
 # Generates C# documents
 rm -rf "${PAGES_PATH}/csharp"
+echo "Generating C# documents in Docker..."
 docker run --rm -it \
     -v "$(pwd)":/work \
     -w /work/src/csharp/docfx \
@@ -86,6 +88,7 @@ mv src/csharp/docfx/html "${PAGES_PATH}/csharp"
 
 # Generates Python documents
 rm -rf "${PAGES_PATH}/python"
+echo "Generating Python documents in Docker..."
 docker run --rm -it \
     -v "$(pwd)":/work \
     -w /work \