- Move a2a.proto to specification/ root - Update build scripts and macros to support new proto location - Fix broken internal links and anchor references in specification.md - Update .gitignore to properly exclude generated SDK docs - Configure Sphinx to suppress external SDK warnings - Fix MkDocs redirects and Python SDK toctree structure --------- Signed-off-by: Luca Muscariello <muscariello@ieee.org>
85 lines
2.6 KiB
Bash
Executable File
85 lines
2.6 KiB
Bash
Executable File
#!/bin/bash
|
|
set -euo pipefail
|
|
|
|
# Unified docs build script that ensures the non-normative JSON artifact is
|
|
# regenerated (if stale) before invoking MkDocs. Uses pure shell.
|
|
|
|
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|
|
|
SCHEMA_JSON="$ROOT_DIR/specification/json/a2a.json"
|
|
PROTO_SRC="$ROOT_DIR/specification/a2a.proto"
|
|
SPEC_SITE_DIR="$ROOT_DIR/docs/spec"
|
|
SCHEMA_JSON_SITE_FILE="$SPEC_SITE_DIR/a2a.json"
|
|
PROTO_SITE_FILE="$SPEC_SITE_DIR/a2a.proto"
|
|
PROTO_TO_SCHEMA_SCRIPT="$ROOT_DIR/scripts/proto_to_json_schema.sh"
|
|
|
|
regen_needed() {
|
|
if [ ! -f "$SCHEMA_JSON" ]; then return 0; fi
|
|
|
|
local proto_mtime
|
|
local schema_mtime
|
|
if [[ "$(uname)" == "Darwin" ]]; then
|
|
proto_mtime=$(stat -f %m "$PROTO_SRC")
|
|
schema_mtime=$(stat -f %m "$SCHEMA_JSON")
|
|
else
|
|
proto_mtime=$(stat -c %Y "$PROTO_SRC")
|
|
schema_mtime=$(stat -c %Y "$SCHEMA_JSON")
|
|
fi
|
|
[ "$proto_mtime" -gt "$schema_mtime" ]
|
|
}
|
|
|
|
echo "[build_docs] Checking schema freshness..." >&2
|
|
if regen_needed; then
|
|
echo "[build_docs] Regenerating a2a.json from proto" >&2
|
|
if [ -x "$PROTO_TO_SCHEMA_SCRIPT" ]; then
|
|
bash "$PROTO_TO_SCHEMA_SCRIPT" "$SCHEMA_JSON" || {
|
|
echo "[build_docs] Warning: proto to JSON schema conversion failed" >&2
|
|
}
|
|
else
|
|
echo "[build_docs] proto_to_json_schema.sh missing or not executable; skipping schema generation." >&2
|
|
fi
|
|
else
|
|
echo "[build_docs] Schema is up-to-date, skipping regeneration" >&2
|
|
fi
|
|
|
|
# Always ensure spec files are available in docs directory for MkDocs
|
|
mkdir -p "$SPEC_SITE_DIR"
|
|
|
|
if [ -f "$SCHEMA_JSON" ]; then
|
|
cp "$SCHEMA_JSON" "$SCHEMA_JSON_SITE_FILE"
|
|
echo "[build_docs] Published schema to $SCHEMA_JSON_SITE_FILE" >&2
|
|
else
|
|
echo "[build_docs] Warning: Schema file not found at $SCHEMA_JSON - MkDocs may fail" >&2
|
|
fi
|
|
|
|
if [ -f "$PROTO_SRC" ]; then
|
|
cp "$PROTO_SRC" "$PROTO_SITE_FILE"
|
|
echo "[build_docs] Published proto to $PROTO_SITE_FILE" >&2
|
|
else
|
|
echo "[build_docs] Warning: Proto file not found at $PROTO_SRC" >&2
|
|
fi
|
|
|
|
# Build SDK documentation
|
|
echo "[build_docs] Building SDK documentation..." >&2
|
|
SDK_DOCS_SCRIPT="$ROOT_DIR/scripts/build_sdk_docs.sh"
|
|
if [ -x "$SDK_DOCS_SCRIPT" ]; then
|
|
bash "$SDK_DOCS_SCRIPT" || echo "[build_docs] Warning: SDK docs build failed" >&2
|
|
else
|
|
echo "[build_docs] SDK docs script not found or not executable: $SDK_DOCS_SCRIPT" >&2
|
|
fi
|
|
|
|
# Add venv bin to PATH to ensure mike finds mkdocs and plugins
|
|
if [ -d "$ROOT_DIR/.doc-venv/bin" ]; then
|
|
export PATH="$ROOT_DIR/.doc-venv/bin:$PATH"
|
|
fi
|
|
|
|
if [ "${1:-}" = "deploy" ]; then
|
|
shift
|
|
echo "[build_docs] Deploying with mike..." >&2
|
|
mike deploy "$@"
|
|
else
|
|
echo "[build_docs] Building MkDocs site..." >&2
|
|
mkdocs build "$@"
|
|
fi
|
|
echo "[build_docs] Done." >&2
|