Automated Concord API doc generation

.github/workflows/docs.yml

@@ -0,0 +1,87 @@
+name: Generate and Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+    paths: 
+      - 'docs-config.json'
+      - 'scripts/Generate-Docs.ps1'
+      - '.github/workflows/docs.yml'
+  schedule:
+    # Run once every three months (1st day of Jan, Apr, Jul, Oct at 2 AM UTC)
+    - cron: '0 2 1 1,4,7,10 *'
+  workflow_dispatch:
+    inputs:
+      force_rebuild:
+        description: 'Force complete rebuild'
+        required: false
+        default: 'false'
+        type: boolean
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  generate-docs:
+    runs-on: windows-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: '8.x'
+
+    - name: Setup NuGet
+      uses: NuGet/setup-nuget@v2
+
+    - name: Install DocFX
+      run: dotnet tool install -g docfx
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v4
+
+    - name: Cache NuGet packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.nuget/packages
+        key: ${{ runner.os }}-nuget-${{ hashFiles('docs-config.json') }}
+        restore-keys: |
+          ${{ runner.os }}-nuget-
+
+    - name: Generate Documentation
+      shell: pwsh
+      run: |
+        if ("${{ github.event.inputs.force_rebuild }}" -eq "true") {
+          & "./scripts/Generate-Docs.ps1" -ConfigFile "docs-config.json" -OutputPath "docs" -Clean
+        } else {
+          & "./scripts/Generate-Docs.ps1" -ConfigFile "docs-config.json" -OutputPath "docs"
+        }
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs/_site
+
+  deploy:
+    needs: generate-docs
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.gitignore

@@ -29,3 +29,10 @@ Microsoft.VisualStudio.Glass
 /Iris/Programs/*.pdb
 /Iris/ic/Properties/launchSettings.json
 /Iris/xplat-package/Properties/launchSettings.json
+
+# DocFX
+docs/_site/
+docs/api/
+docs/docfx.json
+docs/filterConfig.yml
+*.tmp

DOCFX_USAGE.md

@@ -0,0 +1,206 @@
+# DocFX Documentation Generation System
+
+This repository contains a complete solution for generating and hosting API documentation from NuGet packages using DocFX.
+
+## 🚀 Quick Start
+
+### Prerequisites
+- PowerShell 5.1 or later
+- .NET SDK 8.0 or later
+- NuGet CLI (optional, for package version updates)
+- DocFX (installed automatically by scripts)
+
+### Generate Documentation Locally
+
+```powershell
+# Option 1: Generate and serve locally in one command
+.\scripts\Serve-Docs-Local.ps1
+
+# Option 2: Generate only
+.\scripts\Generate-Docs.ps1 -ConfigFile docs-config.json -OutputPath docs
+
+# Option 3: Generate with clean rebuild
+.\scripts\Generate-Docs.ps1 -ConfigFile docs-config.json -OutputPath docs -Clean
+```
+
+After running, the documentation will be available at: `http://localhost:8080`
+
+## 📦 Configuration
+
+Edit `docs-config.json` to configure which NuGet packages to document:
+
+```json
+{
+  "packages": [
+    {
+      "id": "Microsoft.VisualStudio.Debugger.Engine",
+      "version": "17.14.1051801",
+      "description": "Visual Studio Debugger Engine APIs and interfaces",
+      "framework": "net472"
+    }
+  ],
+  "docfx": {
+    "siteName": "Visual Studio Debugger Engine Documentation",
+    "siteDescription": "API documentation for Visual Studio Debugger Engine extensibility interfaces",
+    "baseUrl": "https://microsoft.github.io/ConcordExtensibilitySamples/"
+  }
+}
+```
+
+### Package Configuration Options
+- **id**: NuGet package ID
+- **version**: Specific version to document, or "latest" to automatically use the newest available version
+- **description**: Human-readable description for the documentation
+- **framework**: Target framework (e.g., "net472", "netstandard2.0")
+
+#### Version Options
+- **Specific version**: `"17.14.1051801"` - Uses the exact version specified
+- **Latest version**: `"latest"` - Automatically resolves and uses the newest available version from NuGet
+
+Example using latest version:
+```json
+{
+  "packages": [
+    {
+      "id": "Microsoft.VisualStudio.Debugger.Engine",
+      "version": "latest",
+      "description": "Visual Studio Debugger Engine APIs and interfaces",
+      "framework": "netstandard2.0"
+    }
+  ]
+}
+```
+
+## 🔄 Automatic Updates
+
+### GitHub Actions
+The repository includes a GitHub Action (`.github/workflows/docs.yml`) that:
+- Runs automatically on pushes to main branch
+- Runs once every three months to pick up new package versions
+- Can be triggered manually with force rebuild option
+- Deploys to GitHub Pages automatically
+
+## 📁 Generated Structure
+
+```
+docs/
+├── _site/              # Generated static website
+├── api/                # Generated API reference (YAML files)
+├── docfx.json         # DocFX configuration (auto-generated)
+├── index.md           # Documentation homepage
+└── toc.yml            # Table of contents
+```
+
+## 🌐 GitHub Pages Deployment
+
+The documentation is automatically deployed to GitHub Pages at:
+**https://microsoft.github.io/ConcordExtensibilitySamples/**
+
+### Manual Deployment Setup
+1. Go to repository Settings > Pages
+2. Set Source to "GitHub Actions"
+3. The workflow will handle the rest automatically
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+1. **DocFX not found**
+   ```powershell
+   dotnet tool install -g docfx
+   ```
+
+2. **NuGet package download fails**
+   - Check package ID and version in `docs-config.json`
+   - Ensure internet connectivity
+   - Verify package exists on nuget.org
+
+3. **Documentation generation fails**
+   - Check that assemblies were extracted successfully
+   - Verify .NET target framework compatibility
+   - Review DocFX logs for specific errors
+
+4. **GitHub Actions fails**
+   - Check workflow permissions (Pages deployment requires write permissions)
+   - Verify repository has GitHub Pages enabled
+   - Review action logs for specific errors
+
+### Debug Mode
+Run scripts with verbose output:
+```powershell
+$VerbosePreference = "Continue"
+.\scripts\Generate-Docs.ps1 -ConfigFile docs-config.json -Verbose
+```
+
+## 📋 Script Reference
+
+### Generate-Docs.ps1
+Main documentation generation script.
+
+**Parameters:**
+- `-ConfigFile`: Path to configuration JSON file (required)
+- `-OutputPath`: Output directory for generated docs (default: "docs")
+- `-Clean`: Remove existing files before generation
+
+### Serve-Docs-Local.ps1
+Generates and serves documentation locally for development.
+
+**Parameters:**
+- `-ConfigFile`: Path to configuration JSON file (default: "docs-config.json")
+- `-Port`: Port for local web server (default: 8080)
+
+## 🔧 Advanced Configuration
+
+### Custom DocFX Templates
+Modify the `template` array in the generated `docfx.json` to use custom templates:
+
+```json
+{
+  "build": {
+    "template": ["default", "modern", "custom-template-path"]
+  }
+}
+```
+
+### Multiple Package Sources
+Add multiple packages to document different APIs:
+
+```json
+{
+  "packages": [
+    {
+      "id": "Microsoft.VisualStudio.Debugger.Engine",
+      "version": "17.14.1051801",
+      "description": "Visual Studio Debugger Engine APIs",
+      "framework": "net472"
+    },
+    {
+      "id": "Microsoft.VisualStudio.Shell.Framework",
+      "version": "17.0.31902.203", 
+      "description": "Visual Studio Shell Framework",
+      "framework": "net472"
+    }
+  ]
+}
+```
+
+### Custom Metadata
+Add custom metadata to generated documentation:
+
+```json
+{
+  "docfx": {
+    "siteName": "My API Docs",
+    "siteDescription": "Documentation for my APIs",
+    "baseUrl": "https://myorg.github.io/myrepo/",
+    "customMetadata": {
+      "_appFooter": "Copyright © 2025 My Organization",
+      "_appLogoPath": "images/logo.png"
+    }
+  }
+}
+```
+
+## 📝 License
+
+This documentation system is part of the ConcordExtensibilitySamples repository and follows the same licensing terms.

README.md

@@ -1,8 +1,13 @@
-## ConcordExtensibilitySamples
+# ConcordExtensibilitySamples
+
 Visual Studio Debug Engine Extensibility Samples
 
+## Documentation
+
+📚 **[View API Documentation](https://microsoft.github.io/ConcordExtensibilitySamples/)** - Complete API documentation for Visual Studio Debugger Engine extensibility interfaces
+
 ### What are "Concord Extensibility Samples"?
-[Concord](https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/Overview) is the code name for Visual Studio's new debug engine that first shipped in Visual Studio 2012.  Concord was designed to be extensible and this repo contains samples of these extensions.
+[Concord](https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/Overview) is the code name for Visual Studio's new debug engine that first shipped in Visual Studio 2012. Concord was designed to be extensible and this repo contains samples of these extensions.
 
 The samples in this repo currently target Visual Studio 2022 (version 17.0). For older versions of these samples, please see the [VS16 branch](https://github.com/Microsoft/ConcordExtensibilitySamples/tree/VS16).
 
@@ -17,4 +22,24 @@ If you want to dive right into some code for extending the debug engine, take a
 * [Managed Expression Evaluator](https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/Managed-Expression-Evaluator-Sample)
 * [C++ Custom Visualizer](https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/Cpp-Custom-Visualizer-Sample)
 
+## Documentation Generation
+
+This repository automatically generates and hosts API documentation for Visual Studio extensibility interfaces using DocFX. The documentation is built from NuGet packages and deployed to GitHub Pages.
+
+### Local Development
+
+To generate and serve documentation locally:
+
+```powershell
+# Generate and serve docs locally
+.\scripts\Serve-Docs-Local.ps1
+
+# Generate docs only
+.\scripts\Generate-Docs.ps1 -ConfigFile docs-config.json
+```
+
+### Configuration
+
+Edit [`docs-config.json`](docs-config.json) to configure which NuGet packages to document.
+
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

docs-config.json

@@ -0,0 +1,15 @@
+{
+  "packages": [
+    {
+      "id": "Microsoft.VisualStudio.Debugger.Engine",
+      "version": "latest",
+      "description": "Visual Studio Debugger Engine APIs and interfaces",
+      "framework": "netstandard2.0"
+    }
+  ],
+  "docfx": {
+    "siteName": "Visual Studio Debugger Engine Documentation",
+    "siteDescription": "API documentation for Visual Studio Debugger Engine extensibility interfaces",
+    "baseUrl": "https://microsoft.github.io/ConcordExtensibilitySamples/"
+  }
+}

docs/index.md

@@ -0,0 +1,18 @@
+# Visual Studio Debugger Engine Documentation
+
+API documentation for Visual Studio Debugger Engine extensibility interfaces
+
+## API Documentation
+
+This documentation covers the following packages:
+
+- **Microsoft.VisualStudio.Debugger.Engine** [v17.14.1051801](https://www.nuget.org/packages/Microsoft.VisualStudio.Debugger.Engine/17.14.1051801) (latest) - Visual Studio Debugger Engine APIs and interfaces
+
+
+## API Reference
+
+Use the navigation menu above to browse the API Reference for detailed documentation of all types and members.
+
+---
+
+*Generated on 2025-07-22 09:24:24 UTC from NuGet packages*

docs/toc.yml

@@ -0,0 +1,4 @@
+- name: Home
+  href: index.md
+- name: API Reference
+  href: api/