Implement custom xrefService solution for LinksPlatform documentation

[konard]

Summary

This PR implements a comprehensive custom xrefService solution to replace the Microsoft xrefService in DocFX documentation generation, specifically addressing issue #98. The solution supports cross-references to other LinksPlatform packages that aren't available through Microsoft's service.

🔧 Solution Components

1. Custom XRef Service Generators

   • Python script (generate-xref-service.py) for generating custom xref service
   • Node.js alternative (xref-service-generator.js)
   • Both create JSON files for each UID that can be served from static hosting

2. Enhanced DocFX Configuration

   • Updated docfx.json with comprehensive xref array for LinksPlatform xrefmap files
   • Custom xrefService URLs with Microsoft service as fallback
   • Support for all major LinksPlatform packages (Data, Collections, Memory, etc.)

3. Automation & Deployment

   • setup-custom-xref.sh script for easy setup and deployment
   • GitHub Pages compatible output structure
   • Cross-platform support (Python/Node.js)

4. Documentation

   • Comprehensive XREF_SERVICE_SOLUTION.md with implementation details
   • Usage instructions and deployment options
   • Troubleshooting guides and maintenance instructions

🚀 Key Features

• ✅ Complete LinksPlatform Support: Resolves cross-references to all LinksPlatform packages
• ✅ Backward Compatible: Maintains Microsoft xrefService as fallback for .NET BCL types
• ✅ Self-Hosted: No dependency on external services for LinksPlatform types
• ✅ Extensible: Easy to add new packages or modify reference generation
• ✅ Free Hosting: Can be deployed to GitHub Pages at no cost
• ✅ Fast Performance: Static JSON files served from CDN with quick lookup times

🏗️ Architecture

The solution uses a hybrid approach with multiple fallback layers:

1. Local xref array: Direct references to xrefmap.yml files from LinksPlatform repos
2. Custom xrefService: Generated JSON files for LinksPlatform types
3. Microsoft xrefService: Fallback for .NET BCL types

📋 Usage

Quick Setup:

./scripts/setup-custom-xref.sh
# Deploy generated xref/ directory to GitHub Pages
# Update docfx.json with your hosted URL

Manual Setup:

# Using Python
python3 scripts/generate-xref-service.py ./xref

# Or using Node.js  
node scripts/xref-service-generator.js ./xref

🔗 DocFX Configuration Example

{
  "build": {
    "xref": [
      "https://linksplatform.github.io/Data/xrefmap.yml",
      "https://linksplatform.github.io/Collections/xrefmap.yml",
      // ... other LinksPlatform xrefmap files
    ],
    "xrefService": [
      "https://yourdomain.github.io/xref/{uid}.json",
      "https://xref.docs.microsoft.com/query?uid={uid}"
    ]
  }
}

Test Plan

• Generated custom xref service with 64+ LinksPlatform type references
• Verified JSON file format matches DocFX xrefService API expectations
• Tested Python generator script functionality
• Confirmed GitHub Pages compatibility with generated files
• Validated docfx.json configuration syntax
• Documented comprehensive usage and deployment instructions

Files Changed

• XREF_SERVICE_SOLUTION.md - Complete solution documentation
• scripts/generate-xref-service.py - Python xref service generator
• scripts/xref-service-generator.js - Node.js alternative generator
• scripts/setup-custom-xref.sh - Automation script for easy setup
• docfx.json - Enhanced DocFX configuration with custom xrefService
• docfx-with-custom-xref.json - Template for Scripts repository integration

🤖 Generated with Claude Code

---

Resolves #98