mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
Kristopher Overholt
6458159925
* Add Python API docs generation script and Sphinx config * Add Python API reference docs for ADK Python 2.0.0 * Include version and release number in config for built API docs
95 lines
2.8 KiB
Bash
Executable File
95 lines
2.8 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
|
|
PYTHON_VERSION="3.11"
|
|
# Extras from adk-python's pyproject.toml needed for autodoc to import all modules
|
|
PIP_EXTRAS="all,docs,a2a,eval,extensions,slack,agent-identity,otel-gcp,toolbox,db,gcp,mcp,tools"
|
|
|
|
# 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
|
|
|
|
echo "Installing adk-python with 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."
|