Improve XML documentation loading and support for additional Spectre.Console packages

Author: phil-scott-78

Spectre.Docs.slnx

@@ -9,7 +9,6 @@
     <File Path=".github/workflows/publish-to-gh-pages.yml" />
     <File Path=".gitignore" />
     <File Path="README.md" />
-    <File Path="Remove-TagsFromMarkdown.ps1" />
   </Folder>
   <Project Path="Spectre.Docs.Examples/Spectre.Docs.Examples.csproj" />
   <Project Path="Spectre.Docs/Spectre.Docs.csproj" />

Spectre.Docs/Components/Reference/WidgetApiReference.razor

@@ -1,5 +1,4 @@
 @using System.Reflection
-@using Spectre.Console
 @using Spectre.Docs.Services
 @inject XmlDocumentationService XmlDocs
 
@@ -245,13 +244,17 @@
                 return;
             }
 
-            // Get the type from Spectre.Console assembly
-            var assembly = typeof(AnsiConsole).Assembly;
-            var type = assembly.GetType(TypeName);
+            // Get the type from Spectre assemblies
+            Type? type = null;
+            foreach (var assembly in XmlDocumentationService.Assemblies)
+            {
+                type = assembly.GetType(TypeName);
+                if (type != null) break;
+            }
 
             if (type == null)
             {
-                _error = $"Type '{TypeName}' not found in Spectre.Console assembly";
+                _error = $"Type '{TypeName}' not found in Spectre assemblies";
                 return;
             }
 
@@ -364,8 +367,8 @@
 
     private void LoadExtensionMethods(Type type)
     {
-        var assembly = typeof(AnsiConsole).Assembly;
-        var extensionMethods = assembly.GetTypes()
+        var extensionMethods = XmlDocumentationService.Assemblies
+            .SelectMany(GetLoadableTypes)
             .Where(t => t.IsSealed && !t.IsGenericType && !t.IsNested)
             .SelectMany(t => t.GetMethods(BindingFlags.Static | BindingFlags.Public))
             .Where(m => m.IsDefined(typeof(System.Runtime.CompilerServices.ExtensionAttribute), false))
@@ -404,6 +407,18 @@
         }
     }
 
+    private static IEnumerable<Type> GetLoadableTypes(Assembly assembly)
+    {
+        try
+        {
+            return assembly.GetTypes();
+        }
+        catch (ReflectionTypeLoadException ex)
+        {
+            return ex.Types.Where(t => t != null)!;
+        }
+    }
+
     private string GetFriendlyTypeName(Type type)
     {
         if (type == typeof(void)) return "void";

Spectre.Docs/Services/XmlDocumentationService.cs

@@ -5,6 +5,19 @@ namespace Spectre.Docs.Services;
 
 public class XmlDocumentationService
 {
+    private static readonly (string PackageName, string XmlFileName, Type MarkerType)[] _packages =
+    [
+        ("spectre.console", "Spectre.Console.xml", typeof(Console.AnsiConsole)),
+        ("spectre.console.json", "Spectre.Console.Json.xml", typeof(Console.Json.JsonText)),
+        ("spectre.console.imagesharp", "Spectre.Console.ImageSharp.xml", typeof(Console.CanvasImage)),
+        ("spectre.console.cli", "Spectre.Console.Cli.xml", typeof(Console.Cli.CommandApp))
+    ];
+
+    public static IReadOnlyList<Assembly> Assemblies { get; } = _packages
+        .Select(p => p.MarkerType.Assembly)
+        .Distinct()
+        .ToArray();
+
     private readonly Dictionary<string, XmlDocumentation> _documentation = new();
     private bool _isLoaded;
 
@@ -15,7 +28,7 @@ public XmlDocumentationService()
 
     public XmlDocumentation? GetDocumentation(string memberName)
     {
-        return _documentation.TryGetValue(memberName, out var doc) ? doc : null;
+        return _documentation.GetValueOrDefault(memberName);
     }
 
     public XmlDocumentation? GetDocumentation(Type type)
@@ -46,28 +59,29 @@ private void LoadDocumentation()
     {
         if (_isLoaded) return;
 
-        try
+        foreach (var (packageName, xmlFileName, markerType) in _packages)
         {
-            var xmlPath = FindXmlDocumentationPath();
-            if (xmlPath == null || !File.Exists(xmlPath))
+            try
             {
-                // XML documentation file not found - service will return null for all lookups
-                return;
+                var xmlPath = FindXmlDocumentationPath(packageName, xmlFileName, markerType);
+                if (xmlPath != null && File.Exists(xmlPath))
+                {
+                    ParseXmlDocumentation(xmlPath);
+                }
+            }
+            catch (Exception)
+            {
+                // Error loading XML documentation for this package - continue with next
             }
-
-            ParseXmlDocumentation(xmlPath);
-            _isLoaded = true;
-        }
-        catch (Exception)
-        {
-            // Error loading XML documentation - service will return null for all lookups
         }
+
+        _isLoaded = true;
     }
 
-    private string? FindXmlDocumentationPath()
+    private string? FindXmlDocumentationPath(string packageName, string xmlFileName, Type markerType)
     {
         // Strategy 1: Check assembly location (works when XML is copied to output)
-        var assembly = typeof(Spectre.Console.AnsiConsole).Assembly;
+        var assembly = markerType.Assembly;
         var assemblyPath = assembly.Location;
 
         if (!string.IsNullOrEmpty(assemblyPath))
@@ -80,7 +94,7 @@ private void LoadDocumentation()
         }
 
         // Strategy 2: Search NuGet global packages folder
-        var nugetPath = FindInNuGetCache();
+        var nugetPath = FindInNuGetCache(packageName, xmlFileName);
         if (nugetPath != null && File.Exists(nugetPath))
         {
             return nugetPath;
@@ -89,11 +103,11 @@ private void LoadDocumentation()
         return null;
     }
 
-    private string? FindInNuGetCache()
+    private string? FindInNuGetCache(string packageName, string xmlFileName)
     {
         // Get NuGet global packages folder (cross-platform)
         var userProfile = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
-        var nugetFolder = Path.Combine(userProfile, ".nuget", "packages", "spectre.console");
+        var nugetFolder = Path.Combine(userProfile, ".nuget", "packages", packageName);
 
         if (!Directory.Exists(nugetFolder))
         {
@@ -122,7 +136,7 @@ private void LoadDocumentation()
 
             foreach (var tfmDir in tfmDirs)
             {
-                var xmlPath = Path.Combine(tfmDir, "Spectre.Console.xml");
+                var xmlPath = Path.Combine(tfmDir, xmlFileName);
                 if (File.Exists(xmlPath))
                 {
                     return xmlPath;

Spectre.Docs/Spectre.Docs.csproj

@@ -20,5 +20,8 @@
     <PackageReference Include="MyLittleContentEngine.UI" Version="0.0.0-alpha.0.228" />
     <PackageReference Include="SixLabors.ImageSharp" Version="3.1.12" />
     <PackageReference Include="Spectre.Console" Version="0.54.1-alpha.0.7" />
+    <PackageReference Include="Spectre.Console.Cli" Version="1.0.0-alpha.0.11" />
+    <PackageReference Include="Spectre.Console.ImageSharp" Version="0.54.1-alpha.0.7" />
+    <PackageReference Include="Spectre.Console.Json" Version="0.54.1-alpha.0.7" />
   </ItemGroup>
 </Project>