From bece17ce274a87464add8ad804a54036bf3858e2 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Wed, 9 Jul 2025 14:44:28 -0400 Subject: [PATCH 01/17] chore: add meta info to doc (last update time) --- mkdocs.yml | 2 ++ requirements.txt | 1 + 2 files changed, 3 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 1d63373ca..6a5d537f3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,6 +100,8 @@ plugins: 'get-started/local-testing.md': 'get-started/testing.md' 'get-started/tutorial.md': 'tutorials/index.md' 'guides/responsible-agents.md': 'safety/index.md' + - git-revision-date-localized: + type: timeago # Navigation nav: diff --git a/requirements.txt b/requirements.txt index 0cd7a6a39..390ab1c78 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ mkdocs-material==9.6.14 mkdocs-redirects==1.2.2 mkdocs-linkcheck==1.0.6 +mkdocs-git-revision-date-localized-plugin==1.4.7 \ No newline at end of file From 6f1183e70290ebe1a78a90228e93497ac65a7c44 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Wed, 9 Jul 2025 15:33:22 -0400 Subject: [PATCH 02/17] add docs health check --- .github/workflows/docs-health.yml | 71 ++++++++++++++++++++ README.md | 3 +- docs_health_report.md | 25 ++++++++ scripts/check_docs_health.py | 103 ++++++++++++++++++++++++++++++ 4 files changed, 201 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs-health.yml create mode 100644 docs_health_report.md create mode 100644 scripts/check_docs_health.py diff --git a/.github/workflows/docs-health.yml b/.github/workflows/docs-health.yml new file mode 100644 index 000000000..276696a44 --- /dev/null +++ b/.github/workflows/docs-health.yml @@ -0,0 +1,71 @@ +name: Check Docs Health + +on: + schedule: + - cron: '0 0 * * 0' # Run every Sunday at midnight + workflow_dispatch: + +jobs: + docs-health-check: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - name: Checkout code + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.x' + + - name: Run health check script + id: health_check + run: python adk-docs/scripts/check_docs_health.py + + - name: Generate status badge + run: | + PERCENTAGE="${{ steps.health_check.outputs.recent_percentage }}%" + LABEL="Docs" + if [ "${{ steps.health_check.outputs.exit_code }}" -eq 0 ]; then + STATUS_MESSAGE="Healthy ($PERCENTAGE)" + COLOR="34A853" # Google Green + else + STATUS_MESSAGE="Needs Review ($PERCENTAGE)" + COLOR="F4B400" # Google Yellow + fi + # Replace spaces with underscores for shields.io URL compatibility + MESSAGE_URL_FRIENDLY=$(echo "$STATUS_MESSAGE" | sed 's/ /_/g') + curl "https://img.shields.io/badge/$LABEL-$MESSAGE_URL_FRIENDLY-$COLOR" > adk-docs/docs-health-badge.svg + + - name: Check for changes + id: git_status + run: | + if git diff --quiet -- adk-docs/docs_health_report.md adk-docs/docs-health-badge.svg; then + echo "No changes to report." + echo "changed=false" >> $GITHUB_OUTPUT + else + echo "Health report or badge has changed." + echo "changed=true" >> $GITHUB_OUTPUT + fi + + - name: Create Pull Request with changes + if: steps.git_status.outputs.changed == 'true' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + BRANCH_NAME="docs-health/update-${{ github.run_id }}" + git checkout -b $BRANCH_NAME + git add adk-docs/docs_health_report.md adk-docs/docs-health-badge.svg + git commit -m "docs: Update health report and badge" + git push origin $BRANCH_NAME + gh pr create \ + --base "main" \ + --head "$BRANCH_NAME" \ + --title "Docs Health Report Update (${{ github.run_id }})" \ + --body "Automated documentation health report update. Please review and merge." diff --git a/README.md b/README.md index 6eadb5d47..fe6b4b6ce 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ -# Agent Development Kit (ADK) +# Agent Development Kit (ADK) Documentation [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) +[![Docs Health](docs-health-badge.svg)](docs_health_report.md) Agent Development Kit Logo diff --git a/docs_health_report.md b/docs_health_report.md new file mode 100644 index 000000000..d645a457c --- /dev/null +++ b/docs_health_report.md @@ -0,0 +1,25 @@ +# Documentation Health Report + +**Summary:** **85.7%** of documentation pages were updated in the last 4 weeks. A total of **3** page(s) are considered stale (older than 90 days). + +## Detailed Health by Section + +### Root - ✅ Healthy +All 2 page(s) in this section are up-to-date. + +### agents - ⚠️ Needs Review +2 of 5 page(s) in this section are stale: + +- **docs/agents/custom-agents.md**: Last updated 215 days ago +- **docs/agents/multi-agents.md**: Last updated 198 days ago + +### api-reference - ✅ Healthy +All 3 page(s) in this section are up-to-date. + +### get-started - ⚠️ Needs Review +1 of 4 page(s) in this section are stale: + +- **docs/get-started/quickstart.md**: Last updated 301 days ago + +### tools - ✅ Healthy +All 10 page(s) in this section are up-to-date. \ No newline at end of file diff --git a/scripts/check_docs_health.py b/scripts/check_docs_health.py new file mode 100644 index 000000000..fbef4e486 --- /dev/null +++ b/scripts/check_docs_health.py @@ -0,0 +1,103 @@ +import os +import subprocess +from datetime import datetime, timedelta + +# Configuration +STALENESS_THRESHOLD_DAYS = 90 +RECENT_UPDATE_THRESHOLD_WEEKS = 4 +DOCS_DIRECTORY = "docs" +REPORT_FILENAME = "docs_health_report.md" + +def get_last_commit_date(file_path): + """Gets the last commit date of a file.""" + try: + # Use --format=%ci for committer date, ISO 8601 format + commit_date_str = subprocess.check_output( + ["git", "log", "-1", "--format=%ci", file_path] + ).decode("utf-8").strip() + return datetime.strptime(commit_date_str, "%Y-%m-%d %H:%M:%S %z") + except subprocess.CalledProcessError: + return None + +def check_docs_health(): + """Checks the health of the documentation and generates a detailed report.""" + section_stats = {} + recently_updated_count = 0 + total_docs_count = 0 + total_stale_files = 0 + now = datetime.now(datetime.now().astimezone().tzinfo) + staleness_threshold = now - timedelta(days=STALENESS_THRESHOLD_DAYS) + recent_update_threshold = now - timedelta(weeks=RECENT_UPDATE_THRESHOLD_WEEKS) + + # Change to the adk-docs directory to ensure git commands work correctly + original_cwd = os.getcwd() + script_dir = os.path.dirname(os.path.abspath(__file__)) + adk_docs_root = os.path.abspath(os.path.join(script_dir, "..")) + os.chdir(adk_docs_root) + + for root, _, files in os.walk(DOCS_DIRECTORY): + for file in files: + if file.endswith(".md"): + total_docs_count += 1 + file_path = os.path.join(root, file) + section = os.path.basename(root) if root != DOCS_DIRECTORY else "Root" + + section_stats.setdefault(section, { + "total_files": 0, + "stale_files": [] + }) + section_stats[section]["total_files"] += 1 + + last_commit_date = get_last_commit_date(file_path) + + if last_commit_date: + if last_commit_date < staleness_threshold: + section_stats[section]["stale_files"].append( + (file_path, now - last_commit_date) + ) + total_stale_files += 1 + + if last_commit_date > recent_update_threshold: + recently_updated_count += 1 + + # Revert to original working directory + os.chdir(original_cwd) + + recent_percentage = (recently_updated_count / total_docs_count * 100) if total_docs_count > 0 else 0 + exit_code = 0 if total_stale_files == 0 else 1 + + report_path = os.path.join(adk_docs_root, REPORT_FILENAME) + with open(report_path, "w") as f: + f.write("# Documentation Health Report\n\n") + f.write(f"**Summary:** **{recent_percentage:.1f}%** of documentation pages were updated in the last " + f"{RECENT_UPDATE_THRESHOLD_WEEKS} weeks. ") + f.write(f"A total of **{total_stale_files}** page(s) are considered stale (older than {STALENESS_THRESHOLD_DAYS} days).\n\n") + + if total_stale_files == 0: + f.write("**All documentation is up-to-date!**\n") + print("All documentation is up-to-date.") + else: + f.write("## Detailed Health by Section\n\n") + for section, stats in sorted(section_stats.items()): + stale_count = len(stats["stale_files"]) + if stale_count == 0: + f.write(f"### {section} - ✅ Healthy\n") + f.write(f"All {stats['total_files']} page(s) in this section are up-to-date.\n\n") + else: + f.write(f"### {section} - ⚠️ Needs Review\n") + f.write(f"{stale_count} of {stats['total_files']} page(s) in this section are stale:\n\n") + for file_path, days_since_update in stats["stale_files"]: + f.write(f"- **{file_path}**: Last updated {days_since_update.days} days ago\n") + f.write("\n") + print(f"Found {total_stale_files} stale files.") + + # Set outputs for GitHub Actions + if 'GITHUB_OUTPUT' in os.environ: + with open(os.environ['GITHUB_OUTPUT'], 'a') as f: + f.write(f"recent_percentage={recent_percentage:.1f}\n") + f.write(f"exit_code={exit_code}\n") + + return exit_code + +if __name__ == "__main__": + exit(check_docs_health()) \ No newline at end of file From 6ba61da812ae4eecaaad3f5f65120f720ce551aa Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Wed, 9 Jul 2025 15:43:01 -0400 Subject: [PATCH 03/17] fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fe6b4b6ce..83c02c043 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Agent Development Kit (ADK) Documentation +# Agent Development Kit (ADK) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![Docs Health](docs-health-badge.svg)](docs_health_report.md) From 1ccffee3661902402a5ab2b6d26ce601bb5c0c63 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 14:07:29 -0400 Subject: [PATCH 04/17] update health and version scripts --- .github/workflows/version-report.yml | 58 ++++++++++++++++++++++ docs/agents/index.md | 4 ++ docs_health_report.md | 8 +++- mkdocs.yml | 2 - overrides/main.html | 13 +++++ scripts/check_docs_health.py | 63 +++++++++++++++--------- scripts/generate_version_report.py | 72 ++++++++++++++++++++++++++++ 7 files changed, 194 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/version-report.yml create mode 100644 scripts/generate_version_report.py diff --git a/.github/workflows/version-report.yml b/.github/workflows/version-report.yml new file mode 100644 index 000000000..751ce41d9 --- /dev/null +++ b/.github/workflows/version-report.yml @@ -0,0 +1,58 @@ +name: Generate Version Report + +on: + schedule: + - cron: '0 0 * * *' # Run every day at midnight + workflow_dispatch: + +jobs: + generate-report: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - name: Checkout code + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.x' + + - name: Install dependencies + run: pip install -r requirements.txt + + - name: Generate version report + run: python adk-docs/scripts/generate_version_report.py + + - name: Check for changes + id: git_status + run: | + if git diff --quiet -- adk-docs/docs_health_report.md; then + echo "No changes to report." + echo "changed=false" >> $GITHUB_OUTPUT + else + echo "Version report has changed." + echo "changed=true" >> $GITHUB_OUTPUT + fi + + - name: Create Pull Request with changes + if: steps.git_status.outputs.changed == 'true' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + BRANCH_NAME="docs/version-report-update-${{ github.run_id }}" + git checkout -b $BRANCH_NAME + git add adk-docs/docs_health_report.md + git commit -m "docs: Update version report" + git push origin $BRANCH_NAME + gh pr create \ + --base "main" \ + --head "$BRANCH_NAME" \ + --title "Docs: Update Version Report (${{ github.run_id }})" \ + --body "Automated documentation version report update. Please review and merge." \ No newline at end of file diff --git a/docs/agents/index.md b/docs/agents/index.md index c09ec727e..97592c471 100644 --- a/docs/agents/index.md +++ b/docs/agents/index.md @@ -1,3 +1,7 @@ +--- +version: 1.0 +--- + # Agents In the Agent Development Kit (ADK), an **Agent** is a self-contained execution unit designed to act autonomously to achieve specific goals. Agents can perform tasks, interact with users, utilize external tools, and coordinate with other agents. diff --git a/docs_health_report.md b/docs_health_report.md index d645a457c..c46adb46b 100644 --- a/docs_health_report.md +++ b/docs_health_report.md @@ -1,3 +1,4 @@ + # Documentation Health Report **Summary:** **85.7%** of documentation pages were updated in the last 4 weeks. A total of **3** page(s) are considered stale (older than 90 days). @@ -22,4 +23,9 @@ All 3 page(s) in this section are up-to-date. - **docs/get-started/quickstart.md**: Last updated 301 days ago ### tools - ✅ Healthy -All 10 page(s) in this section are up-to-date. \ No newline at end of file +All 10 page(s) in this section are up-to-date. + + + + + diff --git a/mkdocs.yml b/mkdocs.yml index 6a5d537f3..1d63373ca 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,8 +100,6 @@ plugins: 'get-started/local-testing.md': 'get-started/testing.md' 'get-started/tutorial.md': 'tutorials/index.md' 'guides/responsible-agents.md': 'safety/index.md' - - git-revision-date-localized: - type: timeago # Navigation nav: diff --git a/overrides/main.html b/overrides/main.html index fa266ea52..5291ae5cd 100644 --- a/overrides/main.html +++ b/overrides/main.html @@ -36,3 +36,16 @@ {% endblock %} + + +{% block content %} + {{ super() }} + + {% if page.meta.version %} +
+
+ Version: {{ page.meta.version }} +
+
+ {% endif %} +{% endblock %} diff --git a/scripts/check_docs_health.py b/scripts/check_docs_health.py index fbef4e486..69b7c2905 100644 --- a/scripts/check_docs_health.py +++ b/scripts/check_docs_health.py @@ -1,4 +1,5 @@ import os +import re import subprocess from datetime import datetime, timedelta @@ -11,7 +12,6 @@ def get_last_commit_date(file_path): """Gets the last commit date of a file.""" try: - # Use --format=%ci for committer date, ISO 8601 format commit_date_str = subprocess.check_output( ["git", "log", "-1", "--format=%ci", file_path] ).decode("utf-8").strip() @@ -66,30 +66,47 @@ def check_docs_health(): recent_percentage = (recently_updated_count / total_docs_count * 100) if total_docs_count > 0 else 0 exit_code = 0 if total_stale_files == 0 else 1 + # --- Generate the new report content --- + report_content = "\n" + report_content += "# Documentation Health Report\n\n" + report_content += (f"**Summary:** **{recent_percentage:.1f}%** of documentation pages were updated in the last " + f"{RECENT_UPDATE_THRESHOLD_WEEKS} weeks. ") + report_content += (f"A total of **{total_stale_files}** page(s) are considered stale (older than {STALENESS_THRESHOLD_DAYS} days).\n\n") + + if total_stale_files == 0: + report_content += "**All documentation is up-to-date!**\n" + else: + report_content += "## Detailed Health by Section\n\n" + for section, stats in sorted(section_stats.items()): + stale_count = len(stats["stale_files"]) + if stale_count == 0: + report_content += f"### {section} - ✅ Healthy\n" + report_content += f"All {stats['total_files']} page(s) in this section are up-to-date.\n\n" + else: + report_content += f"### {section} - ⚠️ Needs Review\n" + report_content += f"{stale_count} of {stats['total_files']} page(s) in this section are stale:\n\n" + for file_path, days_since_update in stats["stale_files"]: + report_content += f"- **{file_path}**: Last updated {days_since_update.days} days ago\n" + report_content += "\n" + report_content += "" + + # --- Read the existing report and replace the health section --- report_path = os.path.join(adk_docs_root, REPORT_FILENAME) + try: + with open(report_path, "r") as f: + existing_content = f.read() + except FileNotFoundError: + existing_content = "" + + pattern = re.compile(r".*", re.DOTALL) + + if pattern.search(existing_content): + new_full_content = pattern.sub(report_content, existing_content) + else: + new_full_content = existing_content + "\n\n" + report_content + with open(report_path, "w") as f: - f.write("# Documentation Health Report\n\n") - f.write(f"**Summary:** **{recent_percentage:.1f}%** of documentation pages were updated in the last " - f"{RECENT_UPDATE_THRESHOLD_WEEKS} weeks. ") - f.write(f"A total of **{total_stale_files}** page(s) are considered stale (older than {STALENESS_THRESHOLD_DAYS} days).\n\n") - - if total_stale_files == 0: - f.write("**All documentation is up-to-date!**\n") - print("All documentation is up-to-date.") - else: - f.write("## Detailed Health by Section\n\n") - for section, stats in sorted(section_stats.items()): - stale_count = len(stats["stale_files"]) - if stale_count == 0: - f.write(f"### {section} - ✅ Healthy\n") - f.write(f"All {stats['total_files']} page(s) in this section are up-to-date.\n\n") - else: - f.write(f"### {section} - ⚠️ Needs Review\n") - f.write(f"{stale_count} of {stats['total_files']} page(s) in this section are stale:\n\n") - for file_path, days_since_update in stats["stale_files"]: - f.write(f"- **{file_path}**: Last updated {days_since_update.days} days ago\n") - f.write("\n") - print(f"Found {total_stale_files} stale files.") + f.write(new_full_content) # Set outputs for GitHub Actions if 'GITHUB_OUTPUT' in os.environ: diff --git a/scripts/generate_version_report.py b/scripts/generate_version_report.py new file mode 100644 index 000000000..78ce22639 --- /dev/null +++ b/scripts/generate_version_report.py @@ -0,0 +1,72 @@ +import os +import re +from collections import defaultdict + +def generate_version_report(directory): + version_map = defaultdict(list) + files_without_version = [] + + for root, _, files in os.walk(directory): + for file in files: + if file.endswith(".md"): + filepath = os.path.join(root, file) + with open(filepath, "r") as f: + content = f.read() + if content.startswith("---"): + front_matter = content.split("---")[1] + match = re.search(r"version:\s*(.*)", front_matter) + if match: + version = match.group(1).strip() + version_map[version].append(filepath) + else: + files_without_version.append(filepath) + else: + files_without_version.append(filepath) + + # --- Generate the new report content --- + report_content = "\n" + report_content += "# Documentation Version Report\n\n" + report_content += "This report provides a summary of the versions of the documentation pages.\n\n" + + for version, files in sorted(version_map.items()): + report_content += f"## Version {version}\n\n" + report_content += f"Found {len(files)} pages with this version:\n\n" + for file in files: + link = os.path.relpath(file, "docs").replace(".md", ".html") + report_content += f"- [{file}]({link})\n" + report_content += "\n" + + if files_without_version: + report_content += "## Pages without Version Information\n\n" + report_content += f"Found {len(files_without_version)} pages without version metadata:\n\n" + for file in files_without_version: + link = os.path.relpath(file, "docs").replace(".md", ".html") + report_content += f"- [{file}]({link})\n" + report_content += "\n" + report_content += "" + + # --- Read the existing report and replace the version section --- + report_path = "docs_health_report.md" + try: + with open(report_path, "r") as f: + existing_content = f.read() + except FileNotFoundError: + existing_content = "" + + # Use a regex to replace the content between the markers, or append if not found + # The re.DOTALL flag allows "." to match newlines + pattern = re.compile(r".*", re.DOTALL) + + if pattern.search(existing_content): + new_full_content = pattern.sub(report_content, existing_content) + else: + # If the markers aren't found, append the new report with a newline + new_full_content = existing_content + "\n\n" + report_content + + with open(report_path, "w") as f: + f.write(new_full_content) + + print(f"\nSuccessfully updated version report in {report_path}") + +if __name__ == "__main__": + generate_version_report("docs/") From 465c94b7225dedb0a24ca942a8eacc8bac8e80ac Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 14:09:39 -0400 Subject: [PATCH 05/17] remove the date plugin --- requirements.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 390ab1c78..ab2aa1507 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,3 @@ mkdocs-material==9.6.14 mkdocs-redirects==1.2.2 -mkdocs-linkcheck==1.0.6 -mkdocs-git-revision-date-localized-plugin==1.4.7 \ No newline at end of file +mkdocs-linkcheck==1.0.6 \ No newline at end of file From 388980ee0303e5008c43cca98696e317ed4c42e2 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 14:15:02 -0400 Subject: [PATCH 06/17] update docs path --- scripts/generate_version_report.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/scripts/generate_version_report.py b/scripts/generate_version_report.py index 78ce22639..ebb6ee2f3 100644 --- a/scripts/generate_version_report.py +++ b/scripts/generate_version_report.py @@ -2,11 +2,14 @@ import re from collections import defaultdict -def generate_version_report(directory): +DOCS_DIRECTORY = "docs" +REPORT_FILENAME = "docs_health_report.md" + +def generate_version_report(): version_map = defaultdict(list) files_without_version = [] - for root, _, files in os.walk(directory): + for root, _, files in os.walk(DOCS_DIRECTORY): for file in files: if file.endswith(".md"): filepath = os.path.join(root, file) @@ -46,7 +49,7 @@ def generate_version_report(directory): report_content += "" # --- Read the existing report and replace the version section --- - report_path = "docs_health_report.md" + report_path = os.path.join(DOCS_DIRECTORY, REPORT_FILENAME) try: with open(report_path, "r") as f: existing_content = f.read() @@ -69,4 +72,4 @@ def generate_version_report(directory): print(f"\nSuccessfully updated version report in {report_path}") if __name__ == "__main__": - generate_version_report("docs/") + generate_version_report() From 98bff68df6bd1f2c3c0d17e18e8cb261d246711f Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 14:17:15 -0400 Subject: [PATCH 07/17] add license headers --- scripts/check_docs_health.py | 14 ++++++++++++++ scripts/generate_version_report.py | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/scripts/check_docs_health.py b/scripts/check_docs_health.py index 69b7c2905..a16101800 100644 --- a/scripts/check_docs_health.py +++ b/scripts/check_docs_health.py @@ -1,3 +1,17 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + import os import re import subprocess diff --git a/scripts/generate_version_report.py b/scripts/generate_version_report.py index ebb6ee2f3..ebbbee869 100644 --- a/scripts/generate_version_report.py +++ b/scripts/generate_version_report.py @@ -1,3 +1,17 @@ +# Copyright 2025 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + import os import re from collections import defaultdict From df820a82be17c376fc2e03c094b283e3fd919027 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 15:32:42 -0400 Subject: [PATCH 08/17] remove svg badge and minor refactor --- .github/workflows/docs-health.yml | 26 ++++++-------------------- .github/workflows/version-report.yml | 6 +++--- scripts/check_docs_health.py | 3 ++- 3 files changed, 11 insertions(+), 24 deletions(-) diff --git a/.github/workflows/docs-health.yml b/.github/workflows/docs-health.yml index 276696a44..3636a27d0 100644 --- a/.github/workflows/docs-health.yml +++ b/.github/workflows/docs-health.yml @@ -24,27 +24,13 @@ jobs: - name: Run health check script id: health_check - run: python adk-docs/scripts/check_docs_health.py - - - name: Generate status badge - run: | - PERCENTAGE="${{ steps.health_check.outputs.recent_percentage }}%" - LABEL="Docs" - if [ "${{ steps.health_check.outputs.exit_code }}" -eq 0 ]; then - STATUS_MESSAGE="Healthy ($PERCENTAGE)" - COLOR="34A853" # Google Green - else - STATUS_MESSAGE="Needs Review ($PERCENTAGE)" - COLOR="F4B400" # Google Yellow - fi - # Replace spaces with underscores for shields.io URL compatibility - MESSAGE_URL_FRIENDLY=$(echo "$STATUS_MESSAGE" | sed 's/ /_/g') - curl "https://img.shields.io/badge/$LABEL-$MESSAGE_URL_FRIENDLY-$COLOR" > adk-docs/docs-health-badge.svg + continue-on-error: true + run: python scripts/check_docs_health.py - name: Check for changes id: git_status run: | - if git diff --quiet -- adk-docs/docs_health_report.md adk-docs/docs-health-badge.svg; then + if git diff --quiet -- docs_health_report.md; then echo "No changes to report." echo "changed=false" >> $GITHUB_OUTPUT else @@ -61,11 +47,11 @@ jobs: git config user.email "github-actions[bot]@users.noreply.github.com" BRANCH_NAME="docs-health/update-${{ github.run_id }}" git checkout -b $BRANCH_NAME - git add adk-docs/docs_health_report.md adk-docs/docs-health-badge.svg - git commit -m "docs: Update health report and badge" + git add docs_health_report.md + git commit -m "docs: Update health report" git push origin $BRANCH_NAME gh pr create \ --base "main" \ --head "$BRANCH_NAME" \ - --title "Docs Health Report Update (${{ github.run_id }})" \ + --title "docs: Update health report (${{ github.run_id }})" \ --body "Automated documentation health report update. Please review and merge." diff --git a/.github/workflows/version-report.yml b/.github/workflows/version-report.yml index 751ce41d9..e99b8f458 100644 --- a/.github/workflows/version-report.yml +++ b/.github/workflows/version-report.yml @@ -26,12 +26,12 @@ jobs: run: pip install -r requirements.txt - name: Generate version report - run: python adk-docs/scripts/generate_version_report.py + run: python scripts/generate_version_report.py - name: Check for changes id: git_status run: | - if git diff --quiet -- adk-docs/docs_health_report.md; then + if git diff --quiet -- docs_health_report.md; then echo "No changes to report." echo "changed=false" >> $GITHUB_OUTPUT else @@ -48,7 +48,7 @@ jobs: git config user.email "github-actions[bot]@users.noreply.github.com" BRANCH_NAME="docs/version-report-update-${{ github.run_id }}" git checkout -b $BRANCH_NAME - git add adk-docs/docs_health_report.md + git add docs_health_report.md git commit -m "docs: Update version report" git push origin $BRANCH_NAME gh pr create \ diff --git a/scripts/check_docs_health.py b/scripts/check_docs_health.py index a16101800..a6d71e416 100644 --- a/scripts/check_docs_health.py +++ b/scripts/check_docs_health.py @@ -122,7 +122,8 @@ def check_docs_health(): with open(report_path, "w") as f: f.write(new_full_content) - # Set outputs for GitHub Actions + # (Not used currently) Set outputs for GitHub Actions + # To be used if SVG badge is to be displayed in README. if 'GITHUB_OUTPUT' in os.environ: with open(os.environ['GITHUB_OUTPUT'], 'a') as f: f.write(f"recent_percentage={recent_percentage:.1f}\n") From e127ef0e08ae0ec000609d33c0240a1278547531 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 15:41:34 -0400 Subject: [PATCH 09/17] test --- docs_health_report.md | 1 + scripts/add_version_metadata.py | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 scripts/add_version_metadata.py diff --git a/docs_health_report.md b/docs_health_report.md index c46adb46b..a4a04c76d 100644 --- a/docs_health_report.md +++ b/docs_health_report.md @@ -28,4 +28,5 @@ All 10 page(s) in this section are up-to-date. + diff --git a/scripts/add_version_metadata.py b/scripts/add_version_metadata.py new file mode 100644 index 000000000..7445c8968 --- /dev/null +++ b/scripts/add_version_metadata.py @@ -0,0 +1,31 @@ +import os +import re + +def add_version_metadata(directory): + for root, _, files in os.walk(directory): + for file in files: + if file.endswith(".md"): + filepath = os.path.join(root, file) + with open(filepath, "r+") as f: + content = f.read() + # Remove the old, incorrect version line if it exists + content = re.sub(r"^version: 1.0\n", "", content) + + if content.startswith("---"): + # Front matter exists, add version if it's not there + if "version:" not in content.split("---")[1]: + parts = content.split("---") + front_matter = parts[1] + body = "---".join(parts[2:]) + new_front_matter = front_matter + "version: 1.0\n" + content = "---" + new_front_matter + "---" + body + else: + # No front matter, create a new one + content = "---\nversion: 1.0\n---\n\n" + content + + f.seek(0) + f.write(content) + f.truncate() + +if __name__ == "__main__": + add_version_metadata("docs/") \ No newline at end of file From 3e219c71639ba0d57ddf63149062860a72d81624 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 15:44:13 -0400 Subject: [PATCH 10/17] delete test file --- scripts/add_version_metadata.py | 31 ------------------------------- 1 file changed, 31 deletions(-) delete mode 100644 scripts/add_version_metadata.py diff --git a/scripts/add_version_metadata.py b/scripts/add_version_metadata.py deleted file mode 100644 index 7445c8968..000000000 --- a/scripts/add_version_metadata.py +++ /dev/null @@ -1,31 +0,0 @@ -import os -import re - -def add_version_metadata(directory): - for root, _, files in os.walk(directory): - for file in files: - if file.endswith(".md"): - filepath = os.path.join(root, file) - with open(filepath, "r+") as f: - content = f.read() - # Remove the old, incorrect version line if it exists - content = re.sub(r"^version: 1.0\n", "", content) - - if content.startswith("---"): - # Front matter exists, add version if it's not there - if "version:" not in content.split("---")[1]: - parts = content.split("---") - front_matter = parts[1] - body = "---".join(parts[2:]) - new_front_matter = front_matter + "version: 1.0\n" - content = "---" + new_front_matter + "---" + body - else: - # No front matter, create a new one - content = "---\nversion: 1.0\n---\n\n" + content - - f.seek(0) - f.write(content) - f.truncate() - -if __name__ == "__main__": - add_version_metadata("docs/") \ No newline at end of file From 86f7792971df7df566acf483dfc8d2c6a37e8e9f Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 15:56:11 -0400 Subject: [PATCH 11/17] refactor report content join and remove svg from readme --- README.md | 1 - docs_health_report.md | 31 +++++++++++++++++++++++-- scripts/check_docs_health.py | 36 +++++++++++++++++------------- scripts/generate_version_report.py | 32 ++++++++++++++------------ 4 files changed, 67 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 4823b3514..ac15f74e9 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # Agent Development Kit (ADK) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) -[![Docs Health](docs-health-badge.svg)](docs_health_report.md) Agent Development Kit Logo diff --git a/docs_health_report.md b/docs_health_report.md index a4a04c76d..f62d00d03 100644 --- a/docs_health_report.md +++ b/docs_health_report.md @@ -1,5 +1,5 @@ -# Documentation Health Report +# Sample Documentation Health Report **Summary:** **85.7%** of documentation pages were updated in the last 4 weeks. A total of **3** page(s) are considered stale (older than 90 days). @@ -28,5 +28,32 @@ All 10 page(s) in this section are up-to-date. +# Sample Documentation Version Report - +This report provides a summary of the versions of the documentation pages. + +## Version 1.0 + +Found 3 pages with this version: + +- [docs/get-started/quickstart.md](get-started/quickstart.html) +- [docs/agents/index.md](agents/index.html) +- [docs/agents/models.md](agents/models.html) + +## Version 1.1 + +Found 5 pages with this version: + +- [docs/index.md](index.html) +- [docs/get-started/installation.md](get-started/installation.html) +- [docs/tools/function-tools.md](tools/function-tools.html) +- [docs/tools/google-cloud-tools.md](tools/google-cloud-tools.html) +- [docs/deploy/gke.md](deploy/gke.html) + +## Pages without Version Information + +Found 2 pages without version metadata: + +- [docs/community.md](community.html) +- [docs/tutorials/agent-team.md](tutorials/agent-team.html) + \ No newline at end of file diff --git a/scripts/check_docs_health.py b/scripts/check_docs_health.py index a6d71e416..a7b7956cb 100644 --- a/scripts/check_docs_health.py +++ b/scripts/check_docs_health.py @@ -22,6 +22,8 @@ RECENT_UPDATE_THRESHOLD_WEEKS = 4 DOCS_DIRECTORY = "docs" REPORT_FILENAME = "docs_health_report.md" +HEALTH_REPORT_START_MARKER = "" +HEALTH_REPORT_END_MARKER = "" def get_last_commit_date(file_path): """Gets the last commit date of a file.""" @@ -43,7 +45,7 @@ def check_docs_health(): staleness_threshold = now - timedelta(days=STALENESS_THRESHOLD_DAYS) recent_update_threshold = now - timedelta(weeks=RECENT_UPDATE_THRESHOLD_WEEKS) - # Change to the adk-docs directory to ensure git commands work correctly + # Change to the adk-docs directory original_cwd = os.getcwd() script_dir = os.path.dirname(os.path.abspath(__file__)) adk_docs_root = os.path.abspath(os.path.join(script_dir, "..")) @@ -81,28 +83,30 @@ def check_docs_health(): exit_code = 0 if total_stale_files == 0 else 1 # --- Generate the new report content --- - report_content = "\n" - report_content += "# Documentation Health Report\n\n" - report_content += (f"**Summary:** **{recent_percentage:.1f}%** of documentation pages were updated in the last " + report_parts = [f"{HEALTH_REPORT_START_MARKER}\n"] + report_parts.append("# Documentation Health Report\n\n") + report_parts.append(f"**Summary:** **{recent_percentage:.1f}%** of documentation pages were updated in the last " f"{RECENT_UPDATE_THRESHOLD_WEEKS} weeks. ") - report_content += (f"A total of **{total_stale_files}** page(s) are considered stale (older than {STALENESS_THRESHOLD_DAYS} days).\n\n") + report_parts.append(f"A total of **{total_stale_files}** page(s) are considered stale (older than {STALENESS_THRESHOLD_DAYS} days).\n\n") if total_stale_files == 0: - report_content += "**All documentation is up-to-date!**\n" + report_parts.append("**All documentation is up-to-date!**\n") else: - report_content += "## Detailed Health by Section\n\n" + report_parts.append("## Detailed Health by Section\n\n") for section, stats in sorted(section_stats.items()): stale_count = len(stats["stale_files"]) if stale_count == 0: - report_content += f"### {section} - ✅ Healthy\n" - report_content += f"All {stats['total_files']} page(s) in this section are up-to-date.\n\n" + report_parts.append(f"### {section} - ✅ Healthy\n") + report_parts.append(f"All {stats['total_files']} page(s) in this section are up-to-date.\n\n") else: - report_content += f"### {section} - ⚠️ Needs Review\n" - report_content += f"{stale_count} of {stats['total_files']} page(s) in this section are stale:\n\n" + report_parts.append(f"### {section} - ⚠️ Needs Review\n") + report_parts.append(f"{stale_count} of {stats['total_files']} page(s) in this section are stale:\n\n") for file_path, days_since_update in stats["stale_files"]: - report_content += f"- **{file_path}**: Last updated {days_since_update.days} days ago\n" - report_content += "\n" - report_content += "" + report_parts.append(f"- **{file_path}**: Last updated {days_since_update.days} days ago\n") + report_parts.append("\n") + report_parts.append(HEALTH_REPORT_END_MARKER) + + report_content = "".join(report_parts) # --- Read the existing report and replace the health section --- report_path = os.path.join(adk_docs_root, REPORT_FILENAME) @@ -112,7 +116,7 @@ def check_docs_health(): except FileNotFoundError: existing_content = "" - pattern = re.compile(r".*", re.DOTALL) + pattern = re.compile(f"{HEALTH_REPORT_START_MARKER}.*{HEALTH_REPORT_END_MARKER}", re.DOTALL) if pattern.search(existing_content): new_full_content = pattern.sub(report_content, existing_content) @@ -132,4 +136,4 @@ def check_docs_health(): return exit_code if __name__ == "__main__": - exit(check_docs_health()) \ No newline at end of file + exit(check_docs_health()) diff --git a/scripts/generate_version_report.py b/scripts/generate_version_report.py index ebbbee869..2717f7f8c 100644 --- a/scripts/generate_version_report.py +++ b/scripts/generate_version_report.py @@ -18,6 +18,8 @@ DOCS_DIRECTORY = "docs" REPORT_FILENAME = "docs_health_report.md" +VERSION_REPORT_START_MARKER = "" +VERSION_REPORT_END_MARKER = "" def generate_version_report(): version_map = defaultdict(list) @@ -41,26 +43,28 @@ def generate_version_report(): files_without_version.append(filepath) # --- Generate the new report content --- - report_content = "\n" - report_content += "# Documentation Version Report\n\n" - report_content += "This report provides a summary of the versions of the documentation pages.\n\n" + report_parts = [f"{VERSION_REPORT_START_MARKER}\n"] + report_parts.append("# Documentation Version Report\n\n") + report_parts.append("This report provides a summary of the versions of the documentation pages.\n\n") for version, files in sorted(version_map.items()): - report_content += f"## Version {version}\n\n" - report_content += f"Found {len(files)} pages with this version:\n\n" + report_parts.append(f"## Version {version}\n\n") + report_parts.append(f"Found {len(files)} pages with this version:\n\n") for file in files: link = os.path.relpath(file, "docs").replace(".md", ".html") - report_content += f"- [{file}]({link})\n" - report_content += "\n" + report_parts.append(f"- [{file}]({link})\n") + report_parts.append("\n") if files_without_version: - report_content += "## Pages without Version Information\n\n" - report_content += f"Found {len(files_without_version)} pages without version metadata:\n\n" - for file in files_without_version: + report_parts.append("## Pages without Version Information\n\n") + report_parts.append(f"Found {len(files_without_version)} pages without version metadata:\n\n") + for file in files: link = os.path.relpath(file, "docs").replace(".md", ".html") - report_content += f"- [{file}]({link})\n" - report_content += "\n" - report_content += "" + report_parts.append(f"- [{file}]({link})\n") + report_parts.append("\n") + report_parts.append(VERSION_REPORT_END_MARKER) + + report_content = "".join(report_parts) # --- Read the existing report and replace the version section --- report_path = os.path.join(DOCS_DIRECTORY, REPORT_FILENAME) @@ -72,7 +76,7 @@ def generate_version_report(): # Use a regex to replace the content between the markers, or append if not found # The re.DOTALL flag allows "." to match newlines - pattern = re.compile(r".*", re.DOTALL) + pattern = re.compile(f"{VERSION_REPORT_START_MARKER}.*{VERSION_REPORT_END_MARKER}", re.DOTALL) if pattern.search(existing_content): new_full_content = pattern.sub(report_content, existing_content) From 2658764a7a3bc3f31074a6076be036433544b6cc Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 16:55:54 -0400 Subject: [PATCH 12/17] update Job IDs --- ...docs-health.yml => docs-health-check.yaml} | 2 +- ...{version-report.yml => version-check.yaml} | 29 +++++++------------ 2 files changed, 11 insertions(+), 20 deletions(-) rename .github/workflows/{docs-health.yml => docs-health-check.yaml} (98%) rename .github/workflows/{version-report.yml => version-check.yaml} (58%) diff --git a/.github/workflows/docs-health.yml b/.github/workflows/docs-health-check.yaml similarity index 98% rename from .github/workflows/docs-health.yml rename to .github/workflows/docs-health-check.yaml index 3636a27d0..4fc63f43a 100644 --- a/.github/workflows/docs-health.yml +++ b/.github/workflows/docs-health-check.yaml @@ -6,7 +6,7 @@ on: workflow_dispatch: jobs: - docs-health-check: + health-check: runs-on: ubuntu-latest permissions: contents: write diff --git a/.github/workflows/version-report.yml b/.github/workflows/version-check.yaml similarity index 58% rename from .github/workflows/version-report.yml rename to .github/workflows/version-check.yaml index e99b8f458..ef71598f2 100644 --- a/.github/workflows/version-report.yml +++ b/.github/workflows/version-check.yaml @@ -1,24 +1,24 @@ name: Generate Version Report on: - schedule: - - cron: '0 0 * * *' # Run every day at midnight - workflow_dispatch: + pull_request: + types: [opened, synchronize] + branches: + - main jobs: - generate-report: + version-check: runs-on: ubuntu-latest permissions: contents: write - pull-requests: write steps: - name: Checkout code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: - fetch-depth: 0 + ref: ${{ github.head_ref }} - name: Set up Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.x' @@ -39,20 +39,11 @@ jobs: echo "changed=true" >> $GITHUB_OUTPUT fi - - name: Create Pull Request with changes + - name: Commit and push changes if: steps.git_status.outputs.changed == 'true' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" - BRANCH_NAME="docs/version-report-update-${{ github.run_id }}" - git checkout -b $BRANCH_NAME git add docs_health_report.md git commit -m "docs: Update version report" - git push origin $BRANCH_NAME - gh pr create \ - --base "main" \ - --head "$BRANCH_NAME" \ - --title "Docs: Update Version Report (${{ github.run_id }})" \ - --body "Automated documentation version report update. Please review and merge." \ No newline at end of file + git push From 82c591a7517daefd9aeab628d82183b1df70d3f8 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 16:58:07 -0400 Subject: [PATCH 13/17] adding manual trigger for version check --- .github/workflows/version-check.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/version-check.yaml b/.github/workflows/version-check.yaml index ef71598f2..46bfff0d3 100644 --- a/.github/workflows/version-check.yaml +++ b/.github/workflows/version-check.yaml @@ -5,6 +5,7 @@ on: types: [opened, synchronize] branches: - main + workflow_dispatch: jobs: version-check: From 4ff88fa672bb2c81ee4d0c5a3579eb6197e90990 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 17:09:15 -0400 Subject: [PATCH 14/17] update console log and version number --- docs/agents/index.md | 2 +- scripts/check_docs_health.py | 1 + scripts/generate_version_report.py | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/agents/index.md b/docs/agents/index.md index 97592c471..4732e4c3c 100644 --- a/docs/agents/index.md +++ b/docs/agents/index.md @@ -1,5 +1,5 @@ --- -version: 1.0 +version: 1.0.0 --- # Agents diff --git a/scripts/check_docs_health.py b/scripts/check_docs_health.py index a7b7956cb..edaa63dbc 100644 --- a/scripts/check_docs_health.py +++ b/scripts/check_docs_health.py @@ -126,6 +126,7 @@ def check_docs_health(): with open(report_path, "w") as f: f.write(new_full_content) + print("Docs Health Analysis done.") # (Not used currently) Set outputs for GitHub Actions # To be used if SVG badge is to be displayed in README. if 'GITHUB_OUTPUT' in os.environ: diff --git a/scripts/generate_version_report.py b/scripts/generate_version_report.py index 2717f7f8c..74c958482 100644 --- a/scripts/generate_version_report.py +++ b/scripts/generate_version_report.py @@ -87,7 +87,7 @@ def generate_version_report(): with open(report_path, "w") as f: f.write(new_full_content) - print(f"\nSuccessfully updated version report in {report_path}") + print(f"\nVersion report analysis done.") if __name__ == "__main__": generate_version_report() From 00534acaa11f0e897a10e3b63a7974fd1614e547 Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 17:17:17 -0400 Subject: [PATCH 15/17] fix files without version --- scripts/generate_version_report.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/generate_version_report.py b/scripts/generate_version_report.py index 74c958482..532f7b30d 100644 --- a/scripts/generate_version_report.py +++ b/scripts/generate_version_report.py @@ -58,7 +58,7 @@ def generate_version_report(): if files_without_version: report_parts.append("## Pages without Version Information\n\n") report_parts.append(f"Found {len(files_without_version)} pages without version metadata:\n\n") - for file in files: + for file in files_without_version: link = os.path.relpath(file, "docs").replace(".md", ".html") report_parts.append(f"- [{file}]({link})\n") report_parts.append("\n") @@ -84,6 +84,7 @@ def generate_version_report(): # If the markers aren't found, append the new report with a newline new_full_content = existing_content + "\n\n" + report_content + print(f"\nWriting version report to: {report_path}") with open(report_path, "w") as f: f.write(new_full_content) From 190e7860971808e8e29cf5f44fc71cee25358eae Mon Sep 17 00:00:00 2001 From: sitalakshmi Date: Mon, 28 Jul 2025 17:20:15 -0400 Subject: [PATCH 16/17] fix wrong report path --- scripts/generate_version_report.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/scripts/generate_version_report.py b/scripts/generate_version_report.py index 532f7b30d..4270579d3 100644 --- a/scripts/generate_version_report.py +++ b/scripts/generate_version_report.py @@ -67,9 +67,8 @@ def generate_version_report(): report_content = "".join(report_parts) # --- Read the existing report and replace the version section --- - report_path = os.path.join(DOCS_DIRECTORY, REPORT_FILENAME) try: - with open(report_path, "r") as f: + with open(REPORT_FILENAME, "r") as f: existing_content = f.read() except FileNotFoundError: existing_content = "" @@ -84,8 +83,8 @@ def generate_version_report(): # If the markers aren't found, append the new report with a newline new_full_content = existing_content + "\n\n" + report_content - print(f"\nWriting version report to: {report_path}") - with open(report_path, "w") as f: + print(f"\nWriting version report to: {REPORT_FILENAME}") + with open(REPORT_FILENAME, "w") as f: f.write(new_full_content) print(f"\nVersion report analysis done.") From 901bc439acd98c5b38d041c1648aa79a9a0edbfb Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 28 Jul 2025 21:20:38 +0000 Subject: [PATCH 17/17] docs: Update version report --- docs_health_report.md | 81 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 67 insertions(+), 14 deletions(-) diff --git a/docs_health_report.md b/docs_health_report.md index f62d00d03..96728b05c 100644 --- a/docs_health_report.md +++ b/docs_health_report.md @@ -28,32 +28,85 @@ All 10 page(s) in this section are up-to-date. -# Sample Documentation Version Report +# Documentation Version Report This report provides a summary of the versions of the documentation pages. -## Version 1.0 +## Version 1.0.0 -Found 3 pages with this version: +Found 1 pages with this version: -- [docs/get-started/quickstart.md](get-started/quickstart.html) - [docs/agents/index.md](agents/index.html) -- [docs/agents/models.md](agents/models.html) -## Version 1.1 +## Pages without Version Information -Found 5 pages with this version: +Found 66 pages without version metadata: - [docs/index.md](index.html) +- [docs/community.md](community.html) +- [docs/contributing-guide.md](contributing-guide.html) +- [docs/mcp/index.md](mcp/index.html) +- [docs/api-reference/index.md](api-reference/index.html) +- [docs/api-reference/java/legal/jquery.md](api-reference/java/legal/jquery.html) +- [docs/api-reference/java/legal/dejavufonts.md](api-reference/java/legal/dejavufonts.html) +- [docs/api-reference/java/legal/jqueryUI.md](api-reference/java/legal/jqueryUI.html) +- [docs/runtime/index.md](runtime/index.html) +- [docs/runtime/runconfig.md](runtime/runconfig.html) +- [docs/safety/index.md](safety/index.html) +- [docs/evaluate/index.md](evaluate/index.html) +- [docs/deploy/agent-engine.md](deploy/agent-engine.html) +- [docs/deploy/index.md](deploy/index.html) +- [docs/deploy/gke.md](deploy/gke.html) +- [docs/deploy/cloud-run.md](deploy/cloud-run.html) +- [docs/grounding/vertex_ai_search_grounding.md](grounding/vertex_ai_search_grounding.html) +- [docs/grounding/google_search_grounding.md](grounding/google_search_grounding.html) +- [docs/artifacts/index.md](artifacts/index.html) +- [docs/get-started/index.md](get-started/index.html) - [docs/get-started/installation.md](get-started/installation.html) +- [docs/get-started/about.md](get-started/about.html) +- [docs/get-started/testing.md](get-started/testing.html) +- [docs/get-started/quickstart.md](get-started/quickstart.html) +- [docs/get-started/streaming/index.md](get-started/streaming/index.html) +- [docs/get-started/streaming/quickstart-streaming-java.md](get-started/streaming/quickstart-streaming-java.html) +- [docs/get-started/streaming/quickstart-streaming.md](get-started/streaming/quickstart-streaming.html) +- [docs/streaming/index.md](streaming/index.html) +- [docs/streaming/streaming-tools.md](streaming/streaming-tools.html) +- [docs/streaming/custom-streaming.md](streaming/custom-streaming.html) +- [docs/streaming/custom-streaming-ws.md](streaming/custom-streaming-ws.html) +- [docs/streaming/configuration.md](streaming/configuration.html) +- [docs/streaming/dev-guide/part1.md](streaming/dev-guide/part1.html) +- [docs/tutorials/index.md](tutorials/index.html) +- [docs/tutorials/agent-team.md](tutorials/agent-team.html) +- [docs/observability/weave.md](observability/weave.html) +- [docs/observability/agentops.md](observability/agentops.html) +- [docs/observability/arize-ax.md](observability/arize-ax.html) +- [docs/observability/phoenix.md](observability/phoenix.html) +- [docs/observability/logging.md](observability/logging.html) - [docs/tools/function-tools.md](tools/function-tools.html) +- [docs/tools/index.md](tools/index.html) +- [docs/tools/third-party-tools.md](tools/third-party-tools.html) - [docs/tools/google-cloud-tools.md](tools/google-cloud-tools.html) -- [docs/deploy/gke.md](deploy/gke.html) - -## Pages without Version Information - -Found 2 pages without version metadata: +- [docs/tools/built-in-tools.md](tools/built-in-tools.html) +- [docs/tools/openapi-tools.md](tools/openapi-tools.html) +- [docs/tools/mcp-tools.md](tools/mcp-tools.html) +- [docs/tools/authentication.md](tools/authentication.html) +- [docs/agents/multi-agents.md](agents/multi-agents.html) +- [docs/agents/custom-agents.md](agents/custom-agents.html) +- [docs/agents/llm-agents.md](agents/llm-agents.html) +- [docs/agents/models.md](agents/models.html) +- [docs/agents/workflow-agents/index.md](agents/workflow-agents/index.html) +- [docs/agents/workflow-agents/sequential-agents.md](agents/workflow-agents/sequential-agents.html) +- [docs/agents/workflow-agents/parallel-agents.md](agents/workflow-agents/parallel-agents.html) +- [docs/agents/workflow-agents/loop-agents.md](agents/workflow-agents/loop-agents.html) +- [docs/context/index.md](context/index.html) +- [docs/events/index.md](events/index.html) +- [docs/callbacks/index.md](callbacks/index.html) +- [docs/callbacks/design-patterns-and-best-practices.md](callbacks/design-patterns-and-best-practices.html) +- [docs/callbacks/types-of-callbacks.md](callbacks/types-of-callbacks.html) +- [docs/sessions/index.md](sessions/index.html) +- [docs/sessions/memory.md](sessions/memory.html) +- [docs/sessions/express-mode.md](sessions/express-mode.html) +- [docs/sessions/state.md](sessions/state.html) +- [docs/sessions/session.md](sessions/session.html) -- [docs/community.md](community.html) -- [docs/tutorials/agent-team.md](tutorials/agent-team.html) \ No newline at end of file