xref: /aosp_15_r20/external/grpc-grpc/tools/distrib/python/docgen.py (revision cc02d7e222339f7a4f6ba5f422e6413f4bd931f2) 
1#!/usr/bin/env python3
2# Copyright 2015 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
16from __future__ import print_function
17
18import argparse
19import os
20import os.path
21import shutil
22import subprocess
23import sys
24import tempfile
25
26import grpc_version
27
28parser = argparse.ArgumentParser()
29parser.add_argument(
30    "--repo-owner", type=str, help="Owner of the GitHub repository to be pushed"
31)
32parser.add_argument(
33    "--doc-branch", type=str, default="python-doc-%s" % grpc_version.VERSION
34)
35args = parser.parse_args()
36
37SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
38PROJECT_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, "..", "..", ".."))
39
40SETUP_PATH = os.path.join(PROJECT_ROOT, "setup.py")
41REQUIREMENTS_PATH = os.path.join(PROJECT_ROOT, "requirements.bazel.txt")
42DOC_PATH = os.path.join(PROJECT_ROOT, "doc/build")
43
44if "VIRTUAL_ENV" in os.environ:
45    VIRTUALENV_DIR = os.environ["VIRTUAL_ENV"]
46    PYTHON_PATH = os.path.join(VIRTUALENV_DIR, "bin", "python")
47    subprocess_arguments_list = []
48else:
49    VIRTUALENV_DIR = os.path.join(SCRIPT_DIR, "distrib_virtualenv")
50    PYTHON_PATH = os.path.join(VIRTUALENV_DIR, "bin", "python")
51    subprocess_arguments_list = [
52        ["python3", "-m", "virtualenv", VIRTUALENV_DIR],
53    ]
54
55subprocess_arguments_list += [
56    [PYTHON_PATH, "-m", "pip", "install", "--upgrade", "pip==19.3.1"],
57    [PYTHON_PATH, "-m", "pip", "install", "-r", REQUIREMENTS_PATH],
58    [PYTHON_PATH, "-m", "pip", "install", "--upgrade", "Sphinx"],
59    [PYTHON_PATH, SETUP_PATH, "doc"],
60]
61
62for subprocess_arguments in subprocess_arguments_list:
63    print("Running command: {}".format(subprocess_arguments))
64    subprocess.check_call(args=subprocess_arguments)
65
66if not args.repo_owner or not args.doc_branch:
67    tty_width = int(os.popen("stty size", "r").read().split()[1])
68    print("-" * tty_width)
69    print("Please check generated Python doc inside doc/build")
70    print(
71        "To push to a GitHub repo, please provide repo owner and doc branch"
72        " name"
73    )
74else:
75    # Create a temporary directory out of tree, checkout gh-pages from the
76    # specified repository, edit it, and push it. It's up to the user to then go
77    # onto GitHub and make a PR against grpc/grpc:gh-pages.
78    repo_parent_dir = tempfile.mkdtemp()
79    print("Documentation parent directory: {}".format(repo_parent_dir))
80    repo_dir = os.path.join(repo_parent_dir, "grpc")
81    python_doc_dir = os.path.join(repo_dir, "python")
82    doc_branch = args.doc_branch
83
84    print("Cloning your repository...")
85    subprocess.check_call(
86        [
87            "git",
88            "clone",
89            "--branch",
90            "gh-pages",
91            "https://github.com/grpc/grpc",
92        ],
93        cwd=repo_parent_dir,
94    )
95    subprocess.check_call(["git", "checkout", "-b", doc_branch], cwd=repo_dir)
96    subprocess.check_call(
97        [
98            "git",
99            "remote",
100            "add",
101            "ssh-origin",
102            "[email protected]:%s/grpc.git" % args.repo_owner,
103        ],
104        cwd=repo_dir,
105    )
106    print("Updating documentation...")
107    shutil.rmtree(python_doc_dir, ignore_errors=True)
108    shutil.copytree(DOC_PATH, python_doc_dir)
109    print(
110        "Attempting to push documentation to %s/%s..."
111        % (args.repo_owner, doc_branch)
112    )
113    try:
114        subprocess.check_call(["git", "add", "--all"], cwd=repo_dir)
115        subprocess.check_call(
116            ["git", "commit", "-m", "Auto-update Python documentation"],
117            cwd=repo_dir,
118        )
119        subprocess.check_call(
120            ["git", "push", "--set-upstream", "ssh-origin", doc_branch],
121            cwd=repo_dir,
122        )
123    except subprocess.CalledProcessError:
124        print(
125            "Failed to push documentation. Examine this directory and push "
126            "manually: {}".format(repo_parent_dir)
127        )
128        sys.exit(1)
129    shutil.rmtree(repo_parent_dir)
130