feat: Enhance documentation generation with new output paths and support for Markdown/AsciiDoc formats

Author: christopherosthues

DotAutoDocConfig.Core/ComponentModel/Attributes/DocumentationAttribute.cs

@@ -2,8 +2,10 @@
 
 namespace DotAutoDocConfig.Core.ComponentModel.Attributes;
 
-[AttributeUsage(AttributeTargets.Class, Inherited = true, AllowMultiple = false)]
-public class DocumentationAttribute(DocumentationFormat format) : Attribute
+[AttributeUsage(AttributeTargets.Class, Inherited = true, AllowMultiple = true)]
+public class DocumentationAttribute(DocumentationFormat format, string outputPath) : Attribute
 {
     public DocumentationFormat Format { get; } = format;
+
+    public string OutputPath { get; set; } = outputPath;
 }

DotAutoDocConfig.Core/ComponentModel/DocumentationFormat.cs

@@ -1,12 +1,9 @@
-using System;
-
 namespace DotAutoDocConfig.Core.ComponentModel;
 
-[Flags]
 public enum DocumentationFormat : byte
 {
     None = 0,
-    AsciiDoc = 1 << 0,
-    Markdown = 1 << 1,
-    Html = 1 << 2
+    AsciiDoc = 1,
+    Markdown = 2,
+    Html = 3
 }

DotAutoDocConfig.Sample.Console/AppConfiguration.cs

@@ -6,7 +6,8 @@ namespace DotAutoDocConfig.Sample.Console;
 /// <summary>
 ///
 /// </summary>
-[Documentation(DocumentationFormat.Markdown | DocumentationFormat.AsciiDoc)]
+[Documentation(DocumentationFormat.Markdown, "docs/AppConfiguration.md")]
+[Documentation(DocumentationFormat.AsciiDoc, "docs/AppConfiguration.adoc")]
 public class AppConfiguration
 {
     public int MaxItems { get; set; } = 100;

DotAutoDocConfig.SourceGenerator.Tests/SourceGeneratorWithAttributesTests.cs

@@ -40,7 +40,7 @@ public IEnumerable<string> Report()
     public async Task GenerateReportMethod()
     {
         // Create an instance of the source generator.
-        SourceGeneratorWithAttributes generator = new();
+        DocumentationSourceGenerator generator = new();
 
         // Source generators should be tested using 'GeneratorDriver'.
         CSharpGeneratorDriver driver = CSharpGeneratorDriver.Create(generator);

DotAutoDocConfig.SourceGenerator/DocumentationGenerators/AsciiDocGenerator.cs

@@ -0,0 +1,36 @@
+using System.Linq;
+using System.Text;
+using Microsoft.CodeAnalysis;
+
+namespace DotAutoDocConfig.SourceGenerator.DocumentationGenerators;
+
+public static class AsciiDocGenerator
+{
+    public static void GenerateAsciiDoc(StringBuilder sb, INamedTypeSymbol classSymbol)
+    {
+        sb.AppendLine("= Configuration Documentation");
+        sb.AppendLine();
+        sb.AppendLine($"== {classSymbol.Name}");
+        sb.AppendLine();
+
+        foreach (var member in classSymbol.GetMembers().OfType<IPropertySymbol>())
+        {
+            // Check for ExcludeFromDocumentation attribute
+            var excludeAttribute = member.GetAttributes()
+                .FirstOrDefault(attr => attr.AttributeClass?.ToDisplayString() ==
+                    "DotAutoDocConfig.Core.ComponentModel.Attributes.ExcludeFromDocumentationAttribute");
+
+            if (excludeAttribute != null)
+            {
+                continue; // Skip this property
+            }
+
+            sb.AppendLine($"=== {member.Name}");
+            sb.AppendLine();
+            sb.AppendLine($"Type: `{member.Type.ToDisplayString()}`");
+            sb.AppendLine();
+            sb.AppendLine($"Default Value: `{GetDefaultValue(member)}`");
+            sb.AppendLine();
+        }
+    }
+}

DotAutoDocConfig.SourceGenerator/DocumentationGenerators/MarkdownGenerator.cs

@@ -0,0 +1,36 @@
+using System.Linq;
+using System.Text;
+using Microsoft.CodeAnalysis;
+
+namespace DotAutoDocConfig.SourceGenerator.DocumentationGenerators;
+
+public static class MarkdownGenerator
+{
+    public static void Generate(StringBuilder sb, INamedTypeSymbol classSymbol)
+    {
+        sb.AppendLine("= Configuration Documentation");
+        sb.AppendLine();
+        sb.AppendLine($"== {classSymbol.Name}");
+        sb.AppendLine();
+
+        foreach (var member in classSymbol.GetMembers().OfType<IPropertySymbol>())
+        {
+            // Check for ExcludeFromDocumentation attribute
+            var excludeAttribute = member.GetAttributes()
+                .FirstOrDefault(attr => attr.AttributeClass?.ToDisplayString() ==
+                                        "DotAutoDocConfig.Core.ComponentModel.Attributes.ExcludeFromDocumentationAttribute");
+
+            if (excludeAttribute != null)
+            {
+                continue; // Skip this property
+            }
+
+            sb.AppendLine($"=== {member.Name}");
+            sb.AppendLine();
+            sb.AppendLine($"Type: `{member.Type.ToDisplayString()}`");
+            sb.AppendLine();
+            sb.AppendLine($"Default Value: `{GetDefaultValue(member)}`");
+            sb.AppendLine();
+        }
+    }
+}

…nerator/SourceGeneratorWithAttributes.cs …enerator/DocumentationSourceGenerator.csDotAutoDocConfig.SourceGenerator/SourceGeneratorWithAttributes.cs renamed to DotAutoDocConfig.SourceGenerator/DocumentationSourceGenerator.cs DotAutoDocConfig.SourceGenerator/SourceGeneratorWithAttributes.cs renamed to DotAutoDocConfig.SourceGenerator/DocumentationSourceGenerator.cs

@@ -2,6 +2,9 @@
 using System.Collections.Immutable;
 using System.Linq;
 using System.Text;
+using DotAutoDocConfig.Core.ComponentModel;
+using DotAutoDocConfig.Core.ComponentModel.Attributes;
+using DotAutoDocConfig.SourceGenerator.Models;
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
 using Microsoft.CodeAnalysis.Text;
@@ -13,42 +16,54 @@ namespace DotAutoDocConfig.SourceGenerator;
 /// A sample source generator that creates a custom report based on class properties. The target class should be annotated with the 'Generators.ReportAttribute' attribute.
 /// When using the source code as a baseline, an incremental source generator is preferable because it reduces the performance overhead.
 /// </summary>
-[Generator]
-public class SourceGeneratorWithAttributes : IIncrementalGenerator
+[Generator(LanguageNames.CSharp)]
+public class DocumentationSourceGenerator : IIncrementalGenerator
 {
-    private const string Namespace = "Generators";
-    private const string AttributeName = "ReportAttribute";
-
-    private const string AttributeSourceCode = $@"// <auto-generated/>
-
-namespace {Namespace}
-{{
-    [System.AttributeUsage(System.AttributeTargets.Class)]
-    public class {AttributeName} : System.Attribute
-    {{
-    }}
-}}";
-
     public void Initialize(IncrementalGeneratorInitializationContext context)
     {
-        // Add the marker attribute to the compilation.
-        context.RegisterPostInitializationOutput(ctx => ctx.AddSource(
-            $"{AttributeName}.g.cs",
-            SourceText.From(AttributeSourceCode, Encoding.UTF8)));
-
         // Filter classes annotated with the [Report] attribute. Only filtered Syntax Nodes can trigger code generation.
         IncrementalValuesProvider<ClassDeclarationSyntax> provider = context.SyntaxProvider
-            .CreateSyntaxProvider(
-                (s, _) => s is ClassDeclarationSyntax,
-                (ctx, _) => GetClassDeclarationForSourceGen(ctx))
-            .Where(t => t.reportAttributeFound)
-            .Select((t, _) => t.Item1);
+            .ForAttributeWithMetadataName(
+                $"{typeof(DocumentationAttribute).Namespace}.{nameof(DocumentationAttribute)}",
+                static (node, _) => node is ClassDeclarationSyntax,
+                static (ctx, _) => (ClassDeclarationSyntax)ctx.TargetNode);
 
         // Generate the source code.
         context.RegisterSourceOutput(context.CompilationProvider.Combine(provider.Collect()),
             ((ctx, t) => GenerateCode(ctx, t.Left, t.Right)));
     }
 
+    private static (INamedTypeSymbol?, List<DocumentationOptionsDataModel>) GetDocumentationDataModels(
+        Compilation compilation,
+        ClassDeclarationSyntax classDeclarationSyntax)
+    {
+        List<DocumentationOptionsDataModel> documentationDataModels = [];
+
+        // We need to get semantic model of the class to retrieve
+        SemanticModel semanticModel = compilation.GetSemanticModel(classDeclarationSyntax.SyntaxTree);
+        if (semanticModel.GetDeclaredSymbol(classDeclarationSyntax) is not INamedTypeSymbol classSymbol)
+            return (null, documentationDataModels);
+        // Go through all attributes of the class.
+        foreach (AttributeData attributeData in classSymbol.GetAttributes())
+        {
+            string attributeName = attributeData.AttributeClass?.ToDisplayString() ?? string.Empty;
+            // Check the full name of the [Documentation] attribute.
+            if (attributeName != $"{typeof(DocumentationAttribute).Namespace}.{nameof(DocumentationAttribute)}")
+                continue;
+            // Retrieve constructor arguments.
+            if (attributeData.ConstructorArguments.Length != 2)
+                continue;
+            DocumentationFormat format = (DocumentationFormat)attributeData.ConstructorArguments[0].Value!;
+            string outputPath = attributeData.ConstructorArguments[1].Value!.ToString() ?? string.Empty;
+            documentationDataModels.Add(new DocumentationOptionsDataModel
+            {
+                Format = format,
+                OutputPath = outputPath
+            });
+        }
+        return (classSymbol, documentationDataModels);
+    }
+
     /// <summary>
     /// Checks whether the Node is annotated with the [Report] attribute and maps syntax context to the specific node type (ClassDeclarationSyntax).
     /// </summary>

DotAutoDocConfig.SourceGenerator/Models/DocumentationDataModel.cs

@@ -0,0 +1,13 @@
+using Microsoft.CodeAnalysis;
+
+namespace DotAutoDocConfig.SourceGenerator.Models;
+
+public class DocumentationDataModel
+{
+    public INamedTypeSymbol ClassSymbol { get; set; } = null!;
+    public string ParameterName { get; set; } = null!;
+    public string ParameterType { get; set; } = null!;
+    public string DefaultValue { get; set; } = null!;
+    public string Summary { get; set; } = null!;
+    public string ExampleValue { get; set; } = null!;
+}

DotAutoDocConfig.SourceGenerator/Models/DocumentationOptionsDataModel.cs

@@ -0,0 +1,10 @@
+using DotAutoDocConfig.Core.ComponentModel;
+
+namespace DotAutoDocConfig.SourceGenerator.Models;
+
+public class DocumentationOptionsDataModel
+{
+    public DocumentationFormat Format { get; set; }
+
+    public string OutputPath { get; set; } = null!;
+}