mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
Kristopher Overholt
3246d98ffb
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
118 lines
3.6 KiB
Bash
Executable File
118 lines
3.6 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
#
|
|
# Generates Python API reference documentation for adk-python using Sphinx.
|
|
# Automatically discovers public modules from the installed package.
|
|
# Outputs HTML to docs/api-reference/python/.
|
|
#
|
|
# This script runs in an isolated temporary directory and does not
|
|
# modify any existing adk-python clones or Python environments.
|
|
#
|
|
# Prerequisites: uv, git
|
|
# Run from: adk-docs repository root
|
|
#
|
|
# Usage: bash tools/python-api-docs/generate.sh <version>
|
|
# Example: bash tools/python-api-docs/generate.sh 2.0.0
|
|
|
|
set -e
|
|
|
|
# Configuration
|
|
|
|
# Python version for the build environment. Must satisfy adk-python's
|
|
# requires-python AND any python_version markers on the extras we install (some
|
|
# optional deps are gated to a specific Python). If extras/modules go missing,
|
|
# check python_version markers in adk-python/pyproject.toml.
|
|
PYTHON_VERSION="3.11"
|
|
|
|
# Optional-dependency groups to skip; all others are installed (derived below).
|
|
PIP_EXTRAS_EXCLUDE="dev,test,benchmark,community"
|
|
|
|
# Validate arguments
|
|
VERSION="${1:-}"
|
|
if [[ -z "$VERSION" ]]; then
|
|
echo "Usage: $0 <version>"
|
|
echo "Example: $0 2.0.0"
|
|
exit 1
|
|
fi
|
|
|
|
if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
|
|
echo "Error: Version must be in X.Y.Z format (e.g., 2.0.0)"
|
|
exit 1
|
|
fi
|
|
|
|
# Check prerequisites
|
|
for cmd in uv git; do
|
|
if ! command -v "$cmd" &> /dev/null; then
|
|
echo "Error: $cmd is required but not installed."
|
|
exit 1
|
|
fi
|
|
done
|
|
|
|
# Validate working directory
|
|
TARGET_DIR="docs/api-reference/python"
|
|
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
|
if [[ ! -d "$TARGET_DIR" ]]; then
|
|
echo "Error: Run this script from the adk-docs repository root."
|
|
exit 1
|
|
fi
|
|
|
|
# Create temp workspace
|
|
WORK_DIR=$(mktemp -d)
|
|
trap 'rm -rf "$WORK_DIR"' EXIT
|
|
echo "Using temp workspace: $WORK_DIR"
|
|
|
|
pushd "$WORK_DIR" > /dev/null || exit 1
|
|
|
|
# Set up Python environment
|
|
uv venv --python "$PYTHON_VERSION"
|
|
source .venv/bin/activate
|
|
|
|
# Clone and install adk-python with all extras for complete autodoc coverage
|
|
echo "Cloning adk-python v${VERSION}..."
|
|
git clone --depth 1 --branch "v${VERSION}" https://github.com/google/adk-python adk-python
|
|
|
|
# Derive extras from pyproject.toml (all groups except the denylist).
|
|
echo "Deriving extras from adk-python/pyproject.toml..."
|
|
PIP_EXTRAS=$(PIP_EXTRAS_EXCLUDE="$PIP_EXTRAS_EXCLUDE" python3 - "adk-python/pyproject.toml" <<'PY'
|
|
import os
|
|
import sys
|
|
import tomllib
|
|
|
|
with open(sys.argv[1], "rb") as f:
|
|
data = tomllib.load(f)
|
|
|
|
exclude = {g.strip() for g in os.environ["PIP_EXTRAS_EXCLUDE"].split(",") if g.strip()}
|
|
groups = data.get("project", {}).get("optional-dependencies", {})
|
|
extras = sorted(g for g in groups if g not in exclude)
|
|
if not extras:
|
|
sys.exit("Error: no optional-dependency groups found in pyproject.toml")
|
|
print(",".join(extras))
|
|
PY
|
|
)
|
|
echo "Installing adk-python with extras: $PIP_EXTRAS"
|
|
uv pip install sphinxcontrib-googleanalytics "./adk-python[$PIP_EXTRAS]"
|
|
|
|
# Set up Sphinx project
|
|
echo "Setting up Sphinx project..."
|
|
mkdir -p sphinx_project/source
|
|
|
|
# Sphinx config files (conf.py, index.rst) are maintained in this script's
|
|
# source/ directory. The module list (google-adk.rst) is generated by
|
|
# discover_modules.py because adk-python does not include these files.
|
|
cp "$SCRIPT_DIR/source/conf.py" sphinx_project/source/
|
|
cp "$SCRIPT_DIR/source/index.rst" sphinx_project/source/
|
|
echo "Discovering modules..."
|
|
python3 "$SCRIPT_DIR/discover_modules.py" sphinx_project/source/google-adk.rst
|
|
|
|
# Build HTML
|
|
echo "Building HTML..."
|
|
sphinx-build -b html sphinx_project/source sphinx_project/build/html 2>&1 | tail -20
|
|
|
|
popd > /dev/null || exit 1
|
|
|
|
# Copy to output directory
|
|
echo "Copying to $TARGET_DIR..."
|
|
rm -rf "$TARGET_DIR"/*
|
|
cp -r "$WORK_DIR/sphinx_project/build/html"/* "$TARGET_DIR/"
|
|
|
|
echo "Done."
|