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