Tonnes of updates to the site documentation and general processes

mkdocs/site/hooks/repo_widget_hook.py

@@ -0,0 +1,132 @@
+"""
+MkDocs Hook for Repository Widget Data Generation
+Fetches repository data and generates JSON files during build
+"""
+
+import json
+import os
+import requests
+from pathlib import Path
+from typing import Dict, Any
+import logging
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def on_pre_build(config: Dict[str, Any]) -> None:
+    """
+    Hook that runs before MkDocs builds the site
+    Generates repository JSON data files
+    """
+    logger.info("Generating repository widget data...")
+    
+    # Define repositories to fetch - all repos from services.md
+    repositories = [
+        # Gitea repositories
+        {
+            "repo": "admin/changemaker.lite",
+            "gitea_url": "https://gitea.bnkops.com",
+            "token": os.getenv("GITEA_TOKEN")
+        },
+        # GitHub repositories  
+        {
+            "repo": "coder/code-server",
+            "github": True
+        },
+        {
+            "repo": "n8n-io/n8n", 
+            "github": True
+        },
+        {
+            "repo": "knadh/listmonk",
+            "github": True
+        },
+        {
+            "repo": "nocodb/nocodb",
+            "github": True
+        },
+        {   "repo": "squidfunk/mkdocs-material",
+            "github": True
+        },
+        {
+            "repo": "gethomepage/homepage",
+            "github": True
+        }
+    ]
+    
+    # Create output directory
+    docs_dir = config.get('docs_dir', 'docs')
+    output_dir = Path(docs_dir) / 'assets' / 'repo-data'
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Generate data for each repository
+    for repo_config in repositories:
+        try:
+            generate_repo_data(repo_config, output_dir)
+        except Exception as e:
+            logger.error(f"Failed to generate data for {repo_config['repo']}: {e}")
+
+def generate_repo_data(repo_config: Dict[str, Any], output_dir: Path) -> None:
+    """Generate JSON data file for a single repository"""
+    
+    repo = repo_config['repo']
+    logger.info(f"Fetching data for {repo}")
+    
+    # Determine API URL and headers
+    if repo_config.get('github'):
+        api_url = f"https://api.github.com/repos/{repo}"
+        headers = {'Accept': 'application/vnd.github.v3+json'}
+        github_token = os.getenv('GITHUB_TOKEN')
+        if github_token:
+            headers['Authorization'] = f'token {github_token}'
+    else:
+        gitea_url = repo_config.get('gitea_url', 'https://gitea.bnkops.com')
+        api_url = f"{gitea_url}/api/v1/repos/{repo}"
+        headers = {'Accept': 'application/json'}
+        token = repo_config.get('token') or os.getenv('GITEA_TOKEN')
+        if token:
+            headers['Authorization'] = f'token {token}'
+    
+    # Fetch repository data
+    try:
+        response = requests.get(api_url, headers=headers, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+    except requests.RequestException as e:
+        logger.error(f"Failed to fetch {repo}: {e}")
+        return
+    
+    # Extract widget data
+    widget_data = {
+        'full_name': data.get('full_name'),
+        'name': data.get('name'),
+        'description': data.get('description'),
+        'html_url': data.get('html_url'),
+        'language': data.get('language'),
+        'stars_count': data.get('stargazers_count') or data.get('stars_count', 0),
+        'forks_count': data.get('forks_count', 0),
+        'open_issues_count': data.get('open_issues_count', 0),
+        'updated_at': data.get('updated_at'),
+        'created_at': data.get('created_at'),
+        'clone_url': data.get('clone_url'),
+        'ssh_url': data.get('ssh_url'),
+        'default_branch': data.get('default_branch', 'main'),
+        'last_build_update': data.get('pushed_at') or data.get('updated_at')
+    }
+    
+    # Generate filename
+    filename = f"{repo.replace('/', '-')}.json"
+    file_path = output_dir / filename
+    
+    # Write JSON file
+    try:
+        with open(file_path, 'w') as f:
+            json.dump(widget_data, f, indent=2)
+        logger.info(f"Generated: {filename}")
+    except Exception as e:
+        logger.error(f"Failed to write {filename}: {e}")
+
+def on_post_build(config: Dict[str, Any]) -> None:
+    """Hook that runs after MkDocs builds the site"""
+    logger.info("Repository widget data generation complete")