Sync fork with upstream google/adk-docs

.github/workflows/build-docs.yaml

@@ -21,12 +21,12 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: 3.x
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache

.github/workflows/feature-matrix-updater.yaml

@@ -9,10 +9,10 @@ jobs:
       pull-requests: write
     steps:
     - name: Checkout adk-docs repo
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Set up Go
-      uses: actions/setup-go@v5
+      uses: actions/setup-go@v6
       with:
         go-version: '1.22'
 
@@ -27,7 +27,7 @@ jobs:
         GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
 
     - name: Create Pull Request
-      uses: peter-evans/create-pull-request@v6
+      uses: peter-evans/create-pull-request@v8
       with:
         token: ${{ secrets.ADK_BOT_GITHUB_TOKEN }}
         commit-message: "feat: propose update to feature matrix"

.github/workflows/go-fmt.yaml

@@ -9,12 +9,12 @@ jobs:
   gofmt:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # Fetch all history for all tags and branches
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@v6
         with:
-          go-version: '1.21'
+          go-version: '1.25'
       - name: Run gofmt on changed files
         run: |
           # List changed Go files in the pull request.

.github/workflows/go-snippets-pr-check.yaml

@@ -30,18 +30,18 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
       with:
         # Fetch the entire history to compare branches in the PR.
         fetch-depth: 0
 
     - name: Set up Go
-      uses: actions/setup-go@v5
+      uses: actions/setup-go@v6
       with:
-        go-version: '1.22'
+        go-version: '1.25'
 
     - name: Cache Go modules
-      uses: actions/cache@v3
+      uses: actions/cache@v5
       with:
         path: ~/go/pkg/mod
         key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}

.github/workflows/link-checker.yaml

@@ -21,12 +21,24 @@ on:
   pull_request:
 
 jobs:
-  markdown-link-check:
+  link-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: tcort/github-action-markdown-link-check@v1
+    - uses: actions/checkout@v6
+
+    - name: Check links
+      uses: lycheeverse/lychee-action@v2
       with:
-        use-quiet-mode: 'yes'
-        use-verbose-mode: 'yes'
-        config-file: '.link-checker-config.json'
+        args: >-
+          --verbose
+          --no-progress
+          --max-retries 5
+          --retry-wait-time 3
+          --host-concurrency 2
+          --host-request-interval 1s
+          --root-dir "$(pwd)/docs"
+          './**/*.md'
+        fail: true
+        failIfEmpty: true
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-docs.yaml

@@ -26,16 +26,16 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Configure Git Credentials
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: 3.x
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache

.github/workflows/python-lint.yaml

@@ -38,7 +38,7 @@ jobs:
     outputs:
       sample_dirs: ${{ steps.get_dirs.outputs.sample_dirs }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
@@ -61,12 +61,12 @@ jobs:
       - get_sample_dirs
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"

.github/workflows/python-tests.yaml

@@ -33,31 +33,40 @@ on:
     - cron: "0 0 * * 0"
 
 jobs:
+  get_sample_dirs:
+    runs-on: ubuntu-latest
+    outputs:
+      sample_dirs: ${{ steps.get_dirs.outputs.sample_dirs }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Get Sample Directories
+        id: get_dirs
+        run: |
+          SAMPLE_DIRS=$( find samples/python -type d -not -path "*/.venv*" -exec test -e '{}'/requirements.txt \; -print | jq -R -s -c 'split("\n") | map(select(. != ""))' )
+          echo "sample_dirs=$SAMPLE_DIRS" >> $GITHUB_OUTPUT
+          echo "SAMPLE_DIRS: $SAMPLE_DIRS"  # For debugging
+
   build:
     runs-on: ubuntu-latest
+    needs:
+      - get_sample_dirs
+    if: ${{ needs.get_sample_dirs.outputs.sample_dirs != '[]' }}
     strategy:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
         sample_dir: ${{ fromJson(needs.get_sample_dirs.outputs.sample_dirs) }}
       fail-fast: false # Important: Don't stop if one matrix configuration fails
 
-    needs:
-      - get_sample_dirs
-
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
-      - name: Get Sample Directories
-        id: get_sample_dirs
-        run: |
-          SAMPLE_DIRS=$( find $PYTHON_DIR -type d -not -path "*/.venv*" -exec test -e '{}'/requirements.txt \; -print )
-          echo "sample_dirs=$SAMPLE_DIRS" >> $GITHUB_OUTPUT
-          echo "SAMPLE_DIRS: $SAMPLE_DIRS"  # For debugging
-
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -84,11 +93,11 @@ jobs:
           fi
 
       - name: Upload pytest test results
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v7
         with:
           name: pytest-results-${{ matrix.python-version }}-${{ matrix.sample_dir }}
           path: |
             pytest.txt
             ./htmlcov/
           retention-days: 30
-        if: ${{ always() }}
+        if: ${{ always() }}

.github/workflows/update-python-docs.yaml

@@ -21,20 +21,20 @@ jobs:
 
     steps:
       - name: Checkout ADK Python repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           repository: google/adk-python
           path: ./adk-python
           token: ${{ secrets.ADK_BOT_GITHUB_TOKEN }}
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
       - name: Authenticate to Google Cloud
         id: auth
-        uses: 'google-github-actions/auth@v2'
+        uses: 'google-github-actions/auth@v3'
         with:
           credentials_json: '${{ secrets.ADK_GCP_SA_KEY }}'
 

.gitignore

@@ -192,5 +192,10 @@ docs/site
 # Claude Code
 .claude
 
+
 # Bash files
 ***/*.sh
+
+# Ignore a local build but keep the directory
+/site/*
+!/site/.gitkeep

.lycheeignore

@@ -0,0 +1,16 @@
+# Lychee link checker ignore file
+# Add regular expressions (one per line) for URLs to exclude from checking.
+# See: https://github.com/lycheeverse/lychee-action
+
+# Google Cloud Console (requires authentication, returns HTTP/2 errors)
+^https://console\.(cloud\.google|developers\.google)\.com
+
+# URL contains bracket placeholder (e.g. /s/[project-id])
+^https://app\.phoenix\.arize\.com/s/\[
+
+# Requires authentication
+^https://postman\.postman\.co/settings/me/
+
+# Rate limits automated requests
+^https://www\.gnu\.org/
+^https://www\.markifact\.com

CONTRIBUTING.md

@@ -93,6 +93,7 @@ We review contributions for integrations based on the following criteria:
 | [Documentation fixes](#documentation-fixes) | Fix typos, broken links, or minor wording improvements |
 | [New documentation](#new-documentation) | Add a new guide, tutorial, or reference page |
 | [Major changes](#major-changes) | Large-scale reorganization or refactoring |
+| [API and CLI reference](#api-and-cli-reference) | Pre-built reference docs generated from upstream ADK repositories |
 | [Integrations](#integrations) | Tools, plugins, observability libraries, user interfaces, or any extensions to ADK agents or agent development |
 
 ### Documentation Fixes
@@ -120,13 +121,29 @@ For large-scale reorganization or refactoring:
 2. Wait for maintainer feedback before starting work
 3. Consider breaking large changes into smaller, reviewable PRs
 
+### API and CLI Reference
+
+For changes to the API and CLI reference pages, **do not edit files in
+`docs/api-reference/` directly.** These are pre-built HTML generated from the
+upstream ADK source repositories and are overwritten each time the docs are
+regenerated.
+
+To contribute to API and CLI reference documentation, make your changes in the
+ADK source repository for the relevant language (for example, adding or updating
+docstrings, exporting new public symbols, etc.).
+
+The reference docs are regenerated periodically, and your changes will be
+included in the next update. See the [ADK Contributing
+Guide](https://adk.dev/community/contributing-guide/) for links to each
+language-specific repository.
+
 ### Integrations
 
 Integrations include third-party tools, plugins, and observability platforms for
 ADK agents. All integrations live under `docs/integrations/`. Examples include
-[GitHub](https://google.github.io/adk-docs/integrations/github/),
-[Daytona](https://google.github.io/adk-docs/integrations/daytona/), and
-[AgentOps](https://google.github.io/adk-docs/integrations/agentops/).
+[GitHub](https://adk.dev/integrations/github/),
+[Daytona](https://adk.dev/integrations/daytona/), and
+[AgentOps](https://adk.dev/integrations/agentops/).
 
 **To contribute an integration:**
 
@@ -147,7 +164,7 @@ ADK agents. All integrations live under `docs/integrations/`. Examples include
     ---
     catalog_title: Integration Name
     catalog_description: A short description of what your integration does
-    catalog_icon: /adk-docs/integrations/assets/<name>.png
+    catalog_icon: /integrations/assets/<name>.png
     ---
 
     # Integration Name