AgentEval: Instructions file for GitHub Copilot

DocFX Instructions for AgentEval

Instructions for working with DocFX documentation generation in AgentEval

Project Setup

File Structure

docs/
├── docfx.json          # Main configuration
├── toc.yml             # Navigation structure
├── index.md            # Landing page
├── api/                # Generated API YAML (git-ignored for *.yml)
├── _site/              # Generated HTML output (git-ignored)
├── images/             # Static images
├── templates/          # Custom templates (material theme)
├── adr/                # Architecture Decision Records
└── showcase/           # Code gallery and examples

Key Configuration (docfx.json)

{
  "metadata": [{
    "src": [{ "src": "../src", "files": ["**/*.csproj"], "exclude": ["AgentEval.MAF.AgentHooks/**"] }],
    "dest": "api",
    "properties": { "TargetFramework": "net10.0" }
  }],
  "build": {
    "template": ["default", "modern", "templates/material"],
    "output": "_site"
  }
}

Build Commands

Full Build (Recommended)

# From repository root
.\scripts\build-documentation.ps1

Step-by-Step

# 1. Build project (generates XML docs)
dotnet build src\AgentEval\AgentEval.csproj --configuration Release

# 2. Generate API metadata (YAML files)
cd docs
docfx metadata

# 3. Build HTML site
docfx build

# 4. Preview locally
docfx serve _site
# Opens at http://localhost:8080

Quick Rebuild (Markdown only)

# Skip metadata regeneration if only editing .md files
cd docs
docfx build
start _site\index.html

Common Issues & Solutions

Issue: API docs not generating

Cause: XML documentation disabled in csproj Fix: Ensure <GenerateDocumentationFile>true</GenerateDocumentationFile> in csproj

Issue: docfx metadata fails

Cause: Build errors in source code Fix: Run dotnet build first and fix any compilation errors

Cause: A project that does not target net10.0. docfx metadata builds every project at the TargetFramework set in docfx.json, so a project without that target has no restored references and fails with CS0246. AgentEval.MAF.AgentHooks (net8.0 only, experimental, not packaged) is excluded for this reason. Fix: Exclude the project in metadata.src.exclude, or add the net10.0 target to it.