1#! /bin/bash
2# Copyright 2020 The gRPC Authors
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8#     http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16# A script to automatically generate API references and push to GitHub.
17# This script covers Core/C++/ObjC/C#/PHP/Python. Due to lack of tooling for
18# Cython, Python document generation unfortunately needs to compile everything.
19# So, this script will take couple minutes to run.
20#
21# Generate and push:
22#
23#     tools/distrib/docgen/all_lang-docgen.sh YOUR_GITHUB_USERNAME
24#
25# Just generate:
26#
27#     tools/distrib/docgen/all_lang-docgen.sh
28#
29
30set -e
31
32# Find out the gRPC version and print it
33GRPC_VERSION="$(grep -m1 -Eo ' version: .*' build_handwritten.yaml | grep -Eo '[0-9][^ ]*')"
34echo "Generating documents for version ${GRPC_VERSION}..."
35
36# Specifies your GitHub user name or generates documents locally
37if [ $# -eq 0 ]; then
38    read -r -p "- Are you sure to generate documents without pushing to GitHub? [y/N] " response
39    if [[ "${response[0]}" =~ ^([yY][eE][sS]|[yY])$ ]]; then
40        GITHUB_USER=''
41    else
42        echo "Generation stopped"
43        exit 1
44    fi
45else
46    if [ $# -eq 1 ]; then
47        GITHUB_USER=$1
48    else
49        echo "Too many arguments!"
50        exit 1
51    fi
52fi
53
54# Exits on pending changes; please double check for unwanted code changes
55git diff --exit-code
56git submodule update --init --recursive
57
58# Changes to project root
59dir=$(dirname "${0}")
60cd "${dir}/../../.."
61
62# Clones the API reference GitHub Pages branch
63PAGES_PATH="/tmp/gh-pages"
64rm -rf "${PAGES_PATH}"
65git clone -o upstream --single-branch https://github.com/grpc/grpc -b gh-pages "${PAGES_PATH}"
66
67# Generates Core / C++ / ObjC / PHP documents
68rm -rf "${PAGES_PATH}/core" "${PAGES_PATH}/cpp" "${PAGES_PATH}/objc" "${PAGES_PATH}/php"
69echo "Generating Core / C++ / ObjC / PHP documents in Docker..."
70docker run --rm -it \
71    -v "$(pwd)":/work/grpc \
72    --user "$(id -u):$(id -g)" \
73    hrektts/doxygen /work/grpc/tools/doxygen/run_doxygen.sh
74mv doc/ref/c++/html "${PAGES_PATH}/cpp"
75mv doc/ref/core/html "${PAGES_PATH}/core"
76mv doc/ref/objc/html "${PAGES_PATH}/objc"
77mv doc/ref/php/html "${PAGES_PATH}/php"
78
79# Generates Python documents
80rm -rf "${PAGES_PATH}/python"
81echo "Generating Python documents in Docker..."
82docker run --rm -it \
83    -v "$(pwd)":/work \
84    -w /work \
85    --user "$(id -u):$(id -g)" \
86    python:3.8 tools/distrib/docgen/_generate_python_doc.sh
87mv doc/build "${PAGES_PATH}/python"
88
89# At this point, document generation is finished.
90echo "================================================================="
91echo "  Successfully generated documents for version ${GRPC_VERSION}."
92echo "================================================================="
93
94echo "Generated docs are in ${PAGES_PATH}, use the internal release script to create a PR."
95