feat: add script to auto-update docs contents

.mise.toml

@@ -0,0 +1,34 @@
+[tools]
+# Node.js - required for Docusaurus (package.json specifies >=18.0)
+node = "20.18.0"
+# Python - required for version tracking script
+python = "3.12"
+# Bun - used for package management and running scripts
+bun = "1.2.13"
+# uv - fast Python package installer and resolver
+uv = "latest"
+
+[tasks.install]
+description = "Install all dependencies"
+run = [
+  "bun install",
+  "uv venv --clear",
+  "uv pip install --python .venv/bin/python -r requirements.txt"
+]
+
+[tasks.start]
+description = "Start local development server"
+run = "bun start"
+
+[tasks.build]
+description = "Build static content"
+run = "bun build"
+
+[tasks.check-version]
+description = "Check Noble version and compare with tracker"
+run = "uv run python scripts/check_noble_version.py"
+
+[tasks.test]
+description = "Run pytest unit tests"
+run = "uv run pytest scripts/check_noble_version/test_*.py -v"
+

.noble_version_tracker.json

@@ -0,0 +1,4 @@
+{
+  "last_tracked_version": "v10.0.0",
+  "last_checked": "2025-11-14T14:36:58.293690+00:00"
+}

README.md

@@ -5,21 +5,30 @@
 ### Installation
 
 ```sh
-$ yarn
+$ bun
 ```
 
 ### Local Development
 
 ```sh
-$ yarn start
+$ bun start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ### Build
 
 ```sh
-$ yarn build
+$ bun build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Updating The Module References
+
+This repository is set up to track the concrete used Noble (and its modules) version and make any required changes to the existing documentation
+based on new changes in the repositories.
+For this purpose, there is a Python script, that retrieves the latest Mainnet upgrade version from the contained list of upgrades
+and checks for the last updated version of the docs.
+If there is a mismatch, the diff between the Noble repository tags is retrieved and prompted to an LLM to generate a list of required changes
+to this repository.

docs/build/endpoints/mainnet.mdx

@@ -4,6 +4,7 @@ description: ""
 sidebar_position: 1
 ---
 
+<!-- TODO: this should rather be one page for both and a nice table? -->
 ### Chain ID: `noble-1`
 
 ### RPC

requirements.txt

@@ -0,0 +1,3 @@
+requests>=2.31.0
+pytest>=8.0.0
+

scripts/check_noble_version.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""
+Noble Documentation Version Tracker
+
+Entry point script that delegates to the package CLI.
+"""
+
+from check_noble_version.cli import main
+
+if __name__ == "__main__":
+    main()

scripts/check_noble_version/__init__.py

@@ -0,0 +1,42 @@
+"""
+Noble Documentation Version Tracker
+
+This package provides functionality to track Noble chain versions and
+generate diffs between versions for documentation updates.
+"""
+
+from check_noble_version.version import parse_version, compare_versions
+from check_noble_version.parser import get_latest_version_from_upgrades
+from check_noble_version.tracker import load_tracker, save_tracker
+from check_noble_version.github import get_diff_between_tags, format_diff_summary
+from check_noble_version.modules import (
+    get_relevant_module_paths,
+    get_module_versions_for_tag,
+    get_module_diffs,
+    MODULE_MAPPINGS,
+)
+from check_noble_version.config import (
+    REPO_ROOT,
+    MAINNET_MDX_PATH,
+    TRACKER_JSON_PATH,
+    GITHUB_REPO,
+)
+
+__all__ = [
+    "parse_version",
+    "compare_versions",
+    "get_latest_version_from_upgrades",
+    "load_tracker",
+    "save_tracker",
+    "get_diff_between_tags",
+    "format_diff_summary",
+    "get_relevant_module_paths",
+    "get_module_versions_for_tag",
+    "get_module_diffs",
+    "MODULE_MAPPINGS",
+    "REPO_ROOT",
+    "MAINNET_MDX_PATH",
+    "TRACKER_JSON_PATH",
+    "GITHUB_REPO",
+]
+

scripts/check_noble_version/cli.py

@@ -0,0 +1,138 @@
+"""Command-line interface for the version tracker."""
+
+import sys
+
+from check_noble_version.config import (
+    MAINNET_MDX_PATH,
+    GITHUB_REPO,
+)
+from check_noble_version.parser import get_latest_version_from_upgrades
+from check_noble_version.tracker import load_tracker, save_tracker
+from check_noble_version.version import compare_versions
+from check_noble_version.github import get_diff_between_tags, format_diff_summary
+from check_noble_version.modules import (
+    get_module_versions_for_tag,
+    get_module_diffs,
+)
+
+
+def main():
+    """Main function to check version and compare with tracker."""
+    print("Noble Documentation Version Tracker")
+    print("=" * 50)
+
+    # Get latest version from upgrades table
+    print(f"\nReading upgrades from: {MAINNET_MDX_PATH}")
+    latest_version = get_latest_version_from_upgrades(MAINNET_MDX_PATH)
+
+    if not latest_version:
+        print("Error: Could not determine latest version from upgrades table", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Latest version in upgrades table: {latest_version}")
+
+    # Load tracker
+    tracker = load_tracker()
+    last_tracked = tracker.get("last_tracked_version")
+
+    if last_tracked:
+        print(f"Last tracked version: {last_tracked}")
+
+        # Compare versions
+        try:
+            comparison = compare_versions(last_tracked, latest_version)
+        except ValueError as e:
+            print(f"\n❌ Error: {e}", file=sys.stderr)
+            print("\nPlease ensure both versions are in the format 'vX.Y.Z' without suffixes.", file=sys.stderr)
+            sys.exit(1)
+
+        if comparison == 0:
+            print("\n✓ Versions match! Documentation is up to date.")
+            # Update last_checked timestamp
+            save_tracker(latest_version)
+            sys.exit(0)
+        elif comparison < 0:
+            print(f"\n⚠ Version mismatch detected!")
+            print(f"  Last tracked: {last_tracked}")
+            print(f"  Latest in docs: {latest_version}")
+            print(f"\n  The documentation has been updated with a new version.")
+            print(f"\n  Generating diff between {last_tracked} and {latest_version}...")
+
+            diff_data = get_diff_between_tags(GITHUB_REPO, last_tracked, latest_version)
+            if diff_data:
+                print("\n" + "=" * 50)
+                print("DIFF SUMMARY")
+                print("=" * 50)
+                print(format_diff_summary(diff_data))
+                print("=" * 50)
+
+                # Get module-specific information
+                print("\n" + "=" * 50)
+                print("MODULE VERSIONS & DIFFS")
+                print("=" * 50)
+
+                # Get module versions for both tags
+                print(f"\nFetching module versions for {last_tracked}...")
+                base_modules = get_module_versions_for_tag(GITHUB_REPO, last_tracked)
+                print(f"Fetching module versions for {latest_version}...")
+                head_modules = get_module_versions_for_tag(GITHUB_REPO, latest_version)
+
+                if base_modules and head_modules:
+                    print("\nModule Version Changes:")
+                    all_module_paths = set(base_modules.keys()) | set(head_modules.keys())
+                    for module_path in sorted(all_module_paths):
+                        base_version = base_modules.get(module_path, "N/A")
+                        head_version = head_modules.get(module_path, "N/A")
+                        if base_version != head_version:
+                            print(f"  {module_path}: {base_version} → {head_version}")
+                        elif base_version != "N/A":
+                            print(f"  {module_path}: {base_version} (unchanged)")
+
+                # Get module-specific diffs
+                print(f"\nFetching module-specific diffs...")
+                module_diffs = get_module_diffs(GITHUB_REPO, last_tracked, latest_version)
+
+                if module_diffs:
+                    print("\nModule-Specific Changes:")
+                    for module_path, diff_info in sorted(module_diffs.items()):
+                        file_count = len(diff_info['files'])
+                        additions = diff_info['total_additions']
+                        deletions = diff_info['total_deletions']
+                        changes = diff_info['total_changes']
+                        print(f"\n  {module_path}:")
+                        print(f"    Files changed: {file_count}")
+                        print(f"    Changes: +{additions}, -{deletions} ({changes} total)")
+                        if file_count <= 10:
+                            for file_info in diff_info['files']:
+                                status = file_info.get('status', 'unknown')
+                                filename = file_info.get('filename', 'unknown')
+                                print(f"      [{status}] {filename}")
+                        else:
+                            for file_info in diff_info['files'][:5]:
+                                status = file_info.get('status', 'unknown')
+                                filename = file_info.get('filename', 'unknown')
+                                print(f"      [{status}] {filename}")
+                            print(f"      ... and {file_count - 5} more files")
+                else:
+                    print("\n  No changes detected in tracked modules.")
+
+                print("=" * 50)
+            else:
+                print(f"\n  ⚠ Could not fetch diff from GitHub API.")
+                print(f"  You can view the comparison manually at:")
+                print(f"  https://github.com/{GITHUB_REPO}/compare/{last_tracked}...{latest_version}")
+        else:
+            print(f"\n⚠ Warning: Last tracked version ({last_tracked}) is newer than latest in docs ({latest_version})")
+            print("  This shouldn't happen - the docs may have been reverted.")
+    else:
+        print("\nNo previous version tracked (first run)")
+        print(f"Setting initial tracked version to: {latest_version}")
+        save_tracker(latest_version)
+        print("\n✓ Tracker initialized. Run again to check for updates.")
+
+    print("\n" + "=" * 50)
+
+
+if __name__ == "__main__":
+    main()
+

scripts/check_noble_version/config.py

@@ -0,0 +1,16 @@
+"""Configuration constants for the version tracker."""
+
+from pathlib import Path
+
+# Repository root (parent of scripts directory)
+REPO_ROOT = Path(__file__).parent.parent.parent
+
+# Path to mainnet upgrades documentation
+MAINNET_MDX_PATH = REPO_ROOT / "docs" / "build" / "chain-upgrades" / "mainnet.mdx"
+
+# Path to version tracker JSON file
+TRACKER_JSON_PATH = REPO_ROOT / ".noble_version_tracker.json"
+
+# GitHub repository
+GITHUB_REPO = "noble-assets/noble"
+