Documentation Pipeline

// Resolve from DI
var manager = serviceProvider.GetRequiredService<DocumentationManager>();

// Process assembly
await manager.ProcessAsync("MyLibrary.dll", "MyLibrary.xml");

var assemblies = new[]
{
    ("Core.dll", "Core.xml"),
    ("Extensions.dll", "Extensions.xml"),
    ("Utilities.dll", "Utilities.xml")
};

await manager.ProcessAsync(assemblies);

// Generate placeholders only
await manager.CreateConceptualFilesAsync("MyLibrary.dll", "MyLibrary.xml");

// Later: process with full pipeline
await manager.ProcessAsync("MyLibrary.dll", "MyLibrary.xml");

var context = new ProjectContext
{
    DocumentationRootPath = "docs",
    ShowPlaceholders = false
};

var enrichers = new IDocEnricher[] { /* custom enrichers */ };
var transformers = new IDocTransformer[] { new MarkdownXmlTransformer() };
var renderers = new IDocRenderer[] { new MarkdownRenderer(context) };

var manager = new DocumentationManager(context, enrichers, transformers, renderers);
await manager.ProcessAsync("MyLibrary.dll", "MyLibrary.xml");

public class AiBestPracticesEnricher : IDocEnricher
{
    private readonly IAiService _aiService;

    public AiBestPracticesEnricher(IAiService aiService)
    {
        _aiService = aiService;
    }

    public async Task EnrichAsync(DocEntity entity)
    {
        if (entity is DocAssembly assembly)
        {
            foreach (var ns in assembly.Namespaces)
            {
                foreach (var type in ns.Types)
                {
                    // Only add if not already present
                    if (string.IsNullOrWhiteSpace(type.BestPractices))
                    {
                        type.BestPractices = await _aiService.GenerateBestPracticesAsync(
                            type.Name,
                            type.Summary,
                            type.Members.Select(m => m.Name)
                        );
                    }
                }
            }
        }
    }
}

// Register
services.AddDocEnricher<AiBestPracticesEnricher>();

public class VersionBadgeTransformer : IDocTransformer
{
    public Task TransformAsync(DocEntity entity)
    {
        if (entity is DocType type)
        {
            // Add version badge to summary
            var versionBadge = GetVersionBadge(type);
            if (!string.IsNullOrWhiteSpace(versionBadge))
            {
                type.Summary = $"{versionBadge}\n\n{type.Summary}";
            }
        }

        return Task.CompletedTask;
    }

    private string GetVersionBadge(DocType type)
    {
        // Check for [Obsolete] attribute
        if (type.Symbol.GetAttributes().Any(a => a.AttributeClass?.Name == "ObsoleteAttribute"))
        {
            return "⚠️ **Deprecated**";
        }

        // Check for custom version attributes
        var versionAttr = type.Symbol.GetAttributes()
            .FirstOrDefault(a => a.AttributeClass?.Name == "ApiVersionAttribute");

        if (versionAttr?.ConstructorArguments.Length > 0)
        {
            var version = versionAttr.ConstructorArguments[0].Value;
            return $"✨ **Since v{version}**";
        }

        return string.Empty;
    }
}

// Register
services.AddDocTransformer<VersionBadgeTransformer>();

public class HtmlRenderer : RendererBase, IDocRenderer
{
    public HtmlRenderer(ProjectContext context) : base(context)
    {
    }

    public async Task RenderAsync(DocAssembly model)
    {
        var outputPath = Path.Combine(Context.DocumentationRootPath, "html");
        Directory.CreateDirectory(outputPath);

        foreach (var ns in model.Namespaces)
        {
            var html = GenerateNamespaceHtml(ns);
            var filePath = Path.Combine(outputPath, $"{ns.Name}.html");
            await File.WriteAllTextAsync(filePath, html);

            foreach (var type in ns.Types)
            {
                var typeHtml = GenerateTypeHtml(type);
                var typeFilePath = Path.Combine(outputPath, $"{type.FullName}.html");
                await File.WriteAllTextAsync(typeFilePath, typeHtml);
            }
        }
    }

    public Task RenderPlaceholdersAsync(DocAssembly model)
    {
        // HTML renderer doesn't generate placeholders
        return Task.CompletedTask;
    }

    private string GenerateNamespaceHtml(DocNamespace ns)
    {
        return $@"
            <!DOCTYPE html>
            <html>
            <head><title>{ns.Name}</title></head>
            <body>
                <h1>{ns.Name}</h1>
                <p>{ns.Summary}</p>
                <h2>Types</h2>
                <ul>
                    {string.Join("\n", ns.Types.Select(t =>
                        $"<li><a href='{t.FullName}.html'>{t.Name}</a></li>"))}
                </ul>
            </body>
            </html>
        ";
    }

    private string GenerateTypeHtml(DocType type)
    {
        // Generate full HTML for type...
        return $"<!DOCTYPE html><html>...</html>";
    }
}

// Register
services.AddDocRenderer<HtmlRenderer>();