Repository navigation
feat(LLMsDocsGenerator): generate documentation per project #1315
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -28,6 +28,8 @@ public partial class ComponentAnalyzer | |
| private readonly string? _samplesPath; | ||
| private readonly string? _extensionsSourcePath; | ||
| private readonly IReadOnlyDictionary<string, string>? _extensionProjects; | ||
| private readonly bool _singleProject; | ||
| private readonly string? _extensionRepository; | ||
|
|
||
| private CSharpCompilation? _compilation; | ||
| private readonly Dictionary<string, SyntaxTree> _treeByPath = new(StringComparer.OrdinalIgnoreCase); | ||
|
|
@@ -52,10 +54,13 @@ public ComponentAnalyzer(string sourcePath, string? extensionsSourcePath = null, | |
| } | ||
|
|
||
| internal ComponentAnalyzer(string sourcePath, string? extensionsSourcePath, | ||
| IReadOnlyDictionary<string, string>? extensionProjects, bool includeSamples) | ||
| IReadOnlyDictionary<string, string>? extensionProjects, bool includeSamples, bool singleProject = false) | ||
| { | ||
| _sourcePath = sourcePath; | ||
| _componentsPath = Path.Combine(sourcePath, "Components"); | ||
| _singleProject = singleProject; | ||
| _componentsPath = singleProject ? sourcePath : Path.Combine(sourcePath, "Components"); | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Nested project APIs enter the docs When the selected project directory contains a nested test or auxiliary project with discoverable types, the project-wide recursive scans include nested-project sources, and Exclude nested project directories and their source files from compilation and analysis. Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at line 61:
**Nested project APIs enter the docs**
When the selected project directory contains a nested test or auxiliary project with discoverable types, the project-wide recursive scans include nested-project sources, and `AnalyzeProjectServicesAsync` can also include their public services. The generated documentation therefore contains APIs that do not belong to the selected project.
Exclude nested project directories and their source files from compilation and analysis. |
||
| _extensionRepository = singleProject | ||
| ? FindExtensionRepository(sourcePath) : null; | ||
| _samplesPath = includeSamples | ||
| ? Path.Combine(Path.GetDirectoryName(sourcePath)!, "BootstrapBlazor.Server", "Components", "Samples") | ||
| : null; | ||
|
|
@@ -86,14 +91,15 @@ public async Task<List<ComponentInfo>> AnalyzeAllComponentsAsync() | |
| .Concat(Directory.GetFiles(_componentsPath, "*Base.cs", SearchOption.AllDirectories)) | ||
| .Concat(Directory.GetFiles(_componentsPath, "*.razor", SearchOption.AllDirectories) | ||
| .Where(file => !File.Exists(file + ".cs") && _treeByPath.ContainsKey(Path.GetFullPath(file)))) | ||
| .Where(IsCompilableSource) | ||
| .Distinct(StringComparer.OrdinalIgnoreCase); | ||
|
|
||
| var seenTypes = new HashSet<string>(StringComparer.Ordinal); | ||
|
|
||
| foreach (var file in entryFiles) | ||
| { | ||
| var component = AnalyzeEntryFile(file); | ||
| if (component != null && component.Parameters.Count > 0 && seenTypes.Add(component.FullName)) | ||
| if (component != null && (_singleProject || component.Parameters.Count > 0) && seenTypes.Add(component.FullName)) | ||
| { | ||
| components.Add(component); | ||
| } | ||
|
|
@@ -119,7 +125,7 @@ public async Task<List<ComponentInfo>> AnalyzeAllComponentsAsync() | |
| } | ||
|
|
||
| var component = BuildComponentInfo(symbol, declaration, declaration.SyntaxTree.FilePath); | ||
| if (component.Parameters.Count > 0 && seenTypes.Add(component.FullName)) | ||
| if ((_singleProject || component.Parameters.Count > 0) && seenTypes.Add(component.FullName)) | ||
| { | ||
| components.Add(component); | ||
| } | ||
|
|
@@ -226,7 +232,7 @@ public async Task<List<ComponentInfo>> AnalyzeServicesAsync(IEnumerable<string> | |
| return services; | ||
| } | ||
|
|
||
| internal async Task<List<ComponentInfo>> AnalyzeCoreServicesAsync(IEnumerable<ComponentInfo> components) | ||
| internal async Task<List<ComponentInfo>> AnalyzeProjectServicesAsync(IEnumerable<ComponentInfo> components) | ||
| { | ||
| await EnsureCompilationAsync(); | ||
|
|
||
|
|
@@ -240,7 +246,7 @@ internal async Task<List<ComponentInfo>> AnalyzeCoreServicesAsync(IEnumerable<Co | |
| var path = Path.GetFullPath(tree.FilePath); | ||
| var inServices = path.StartsWith(servicePath, StringComparison.OrdinalIgnoreCase); | ||
| var inComponents = path.StartsWith(componentPath, StringComparison.OrdinalIgnoreCase); | ||
| if (!inServices && !inComponents) | ||
| if (!_singleProject && !inServices && !inComponents) | ||
| { | ||
| continue; | ||
| } | ||
|
|
@@ -260,7 +266,9 @@ internal async Task<List<ComponentInfo>> AnalyzeCoreServicesAsync(IEnumerable<Co | |
|
|
||
| var isService = symbol.TypeKind == TypeKind.Interface && | ||
| (inServices || symbol.Name.EndsWith("Service", StringComparison.Ordinal) || symbol.Name.EndsWith("Provider", StringComparison.Ordinal)) | ||
| || symbol.TypeKind == TypeKind.Class && symbol.Name.EndsWith("Service", StringComparison.Ordinal); | ||
| || symbol.TypeKind == TypeKind.Class && | ||
| (symbol.Name.EndsWith("Service", StringComparison.Ordinal) || | ||
| _singleProject && symbol.Name.EndsWith("Provider", StringComparison.Ordinal)); | ||
| if (!isService) | ||
| { | ||
| continue; | ||
|
|
@@ -273,15 +281,25 @@ internal async Task<List<ComponentInfo>> AnalyzeCoreServicesAsync(IEnumerable<Co | |
|
|
||
| if (symbols.TryGetValue(symbol.Name, out var existing) && !SymbolEqualityComparer.Default.Equals(existing, symbol)) | ||
| { | ||
| throw new InvalidDataException($"Core service names collide: {existing.ToDisplayString()} and {symbol.ToDisplayString()}"); | ||
| throw new InvalidDataException($"Service names collide: {existing.ToDisplayString()} and {symbol.ToDisplayString()}"); | ||
| } | ||
|
|
||
| symbols[symbol.Name] = symbol; | ||
| } | ||
| } | ||
|
|
||
| return symbols.Values.OrderBy(symbol => symbol.Name, StringComparer.Ordinal) | ||
| .Select(symbol => BuildServiceInfo(symbol, includeTypeParameters: true)).ToList(); | ||
| .Select(symbol => | ||
| { | ||
| var info = BuildServiceInfo(symbol, includeTypeParameters: true); | ||
| if (_singleProject) | ||
| { | ||
| info.IsExtension = _extensionRepository != null; | ||
| info.SuppressSourceLink = _extensionRepository == null; | ||
| info.Registrations = ResolveRegistrations(symbol, null); | ||
| } | ||
| return info; | ||
| }).ToList(); | ||
| } | ||
|
|
||
| private ComponentInfo BuildServiceInfo(INamedTypeSymbol symbol, bool includeTypeParameters = false) | ||
|
|
@@ -574,6 +592,11 @@ private static List<UsingDirectiveSyntax> ReadProjectUsings(string projectDirect | |
| private async Task<string?> BuildInheritsShimAsync(string razorFile) | ||
| { | ||
| var content = await File.ReadAllTextAsync(razorFile); | ||
| if (_singleProject && (Path.GetFileName(razorFile).StartsWith('_') || | ||
| content.Split('\n').Any(line => line.TrimStart().StartsWith("@page ", StringComparison.Ordinal)))) | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Routable pages enter component docs When a Razor page uses a tab between Recognize Razor directive whitespace with a whitespace-aware check, or parse the directive using Razor syntax. Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at line 596:
**Routable pages enter component docs**
When a Razor page uses a tab between `@page` and its route, a valid Razor `@page` directive separated from its route by a tab does not match the literal `"@page "` check, so `BuildInheritsShimAsync` synthesizes a component for that page and the generator publishes it as a component.
Recognize Razor directive whitespace with a whitespace-aware check, or parse the directive using Razor syntax. |
||
| { | ||
| return null; | ||
|
Comment on lines
+595
to
+598
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Routed pages enter component index When a single-project input contains a routable Apply the Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at lines 595-598:
**Routed pages enter component index**
When a single-project input contains a routable `.razor` page with a `.razor.cs` code-behind file, the page's `.razor.cs` file is still selected as an entry file and `AnalyzeEntryFile` adds its type without checking whether the paired Razor file has `@page`. Routable pages with code-behind therefore appear as components in the generated index despite the new page exclusion.
Apply the `@page` exclusion to the paired Razor/code-behind entry before adding the type to the component list. |
||
| } | ||
|
|
||
| string? baseType = null; | ||
| string? ns = null; | ||
|
|
@@ -601,10 +624,11 @@ private static List<UsingDirectiveSyntax> ReadProjectUsings(string projectDirect | |
| } | ||
| } | ||
|
|
||
| if (string.IsNullOrEmpty(baseType)) | ||
| if (string.IsNullOrEmpty(baseType) && !_singleProject) | ||
| { | ||
| return null; | ||
| } | ||
| baseType ??= "ComponentBase"; | ||
|
|
||
| var className = Path.GetFileNameWithoutExtension(razorFile); | ||
| ns ??= GetNamespaceForRazor(razorFile) ?? "BootstrapBlazor.Components"; | ||
|
|
@@ -695,6 +719,8 @@ private ComponentInfo BuildComponentInfo(INamedTypeSymbol symbol, ClassDeclarati | |
| TypeParameters = symbol.TypeParameters.Select(t => t.Name).ToList(), | ||
| BaseClass = GetBaseClassName(symbol), | ||
| SourcePath = GetRelativePath(filePath), | ||
| IsExtension = _singleProject && _extensionRepository != null, | ||
| SuppressSourceLink = _singleProject && _extensionRepository == null, | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Core source links are omitted When generation targets the BootstrapBlazor core project, Set Also at Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at line 723:
**Core source links are omitted**
When generation targets the BootstrapBlazor core project, `SuppressSourceLink` is set whenever `_extensionRepository` is null, including for the core repository. The Markdown builder therefore omits source links from generated pages despite the available core GitHub raw URL.
Set `SuppressSourceLink` based on whether a source link is actually available, rather than whether an extensions repository was detected.
Also at `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:298`. |
||
| LastModified = File.GetLastWriteTimeUtc(filePath), | ||
| SamplePath = FindSamplePath(symbol.Name), | ||
| Parameters = CollectParameters(symbol), | ||
|
|
@@ -1042,6 +1068,10 @@ private static (bool IsObsolete, string? Message) GetObsoleteInfo(MemberDeclarat | |
| private string GetRelativePath(string fullPath) | ||
| { | ||
| var full = Path.GetFullPath(fullPath); | ||
| if (_singleProject) | ||
| { | ||
| return Path.GetRelativePath(_extensionRepository ?? _sourcePath, full).Replace('\\', '/'); | ||
| } | ||
|
|
||
| // Extension sources live in a separate repository; make the path relative to | ||
| // that repo root (the parent of its src folder). | ||
|
|
@@ -1053,6 +1083,7 @@ private string GetRelativePath(string fullPath) | |
| var extRoot = Path.GetDirectoryName(extSrc)!; | ||
| return Path.GetRelativePath(extRoot, full).Replace('\\', '/'); | ||
| } | ||
|
|
||
| } | ||
|
|
||
| var sourceRoot = Path.GetFullPath(_sourcePath); | ||
|
|
@@ -1065,6 +1096,18 @@ private string GetRelativePath(string fullPath) | |
| return Path.GetRelativePath(basePath, full).Replace('\\', '/'); | ||
| } | ||
|
|
||
| private static string? FindExtensionRepository(string sourcePath) | ||
| { | ||
| for (var directory = new DirectoryInfo(Path.GetFullPath(sourcePath)); directory != null; directory = directory.Parent) | ||
| { | ||
| if (File.Exists(Path.Combine(directory.FullName, "BootstrapBlazor.Extensions.slnx"))) | ||
| { | ||
| return directory.FullName; | ||
| } | ||
| } | ||
| return null; | ||
| } | ||
|
|
||
| private string? FindSamplePath(string componentName) | ||
| { | ||
| if (_samplesPath == null || !Directory.Exists(_samplesPath)) | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟠 High · Non-components appear as components
When the project contains a matching entry file whose class is not a component,
AnalyzeAllComponentsAsyncpasses matching files toAnalyzeEntryFilewithout checkingIsComponentType, and the_singleProjectcondition retains results even when they have no component parameters. The index and generated documents therefore list helper or base classes as components.Filter analyzed entry-file types with
IsComponentTypebefore adding them to the component list.Also at
tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:102.Prompt for AI agents