Skip to content

feat(LLMsDocsGenerator): generate documentation per project - #1315

Merged
ArgoZhang merged 2 commits into
masterfrom
dev-skill-nuget
Nov 17, 2026
Merged

ArgoZhang merged 2 commits into
masterfrom
dev-skill-nuget

Conversation

@ArgoZhang

@ArgoZhang ArgoZhang commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Link issues

fixes #1314

Summary By Copilot

Generate documentation for the current project or --project, discover local components and services, and update the English and Chinese usage guides. Release 11.0.3 with Apache-2.0 license and README package metadata.

Only the two existing branch commits are included; local uncommitted component packaging configurations and test scripts are excluded.

Regression?

  • Yes
  • No

Intentional CLI compatibility break from 11.0.2: remove --root, --core-only, core-repository discovery, and website-wide generation. Callers must migrate to current-project generation or --project.

Risk

  • High
  • Medium
  • Low

Existing publishing commands must migrate. External base members, external service interfaces, and Razor @code members may remain undocumented.

Verification

  • Manual (required)

  • Automated

  • dotnet build .\tools\BootstrapBlazor.LLMsDocsGenerator -c Release --no-restore — passed; zero warnings and errors.

  • dotnet pack .\tools\BootstrapBlazor.LLMsDocsGenerator -c Release --no-build --no-restore — passed; package created without missing-license or missing-readme warnings.

  • No tracked integration tests are included in these commits; local uncommitted tests remain excluded.

Packaging changes reviewed?

  • Yes
  • No
  • N/A

☑️ Self Check before Merge

⚠️ Please check all items below before review. ⚠️

  • Doc is updated/provided or not needed
  • Demo is updated/provided or not needed
  • Merge the latest code from the main branch

The branch is one unrelated EmbedPDF commit behind master; no merge or rebase was performed to preserve the current branch and uncommitted work.

Summary by Sourcery

Adopt single-project documentation generation with a simplified CLI and project-local source analysis.

New Features:

  • Enable LLM documentation generation for a single project selected from the current directory or via --project.
  • Generate component and service documentation with project-specific indexing, categorization, and source-link handling.

Enhancements:

  • Remove repository-wide, core-only, and extension-package discovery in favor of focused project analysis.
  • Improve source analysis for standalone projects, including service discovery and Razor component handling.

Build:

  • Update tool packaging metadata, including release version, Apache-2.0 license, and README package metadata.

Documentation:

  • Revise English and Chinese usage guides for single-project generation, CLI options, output structure, and analysis limitations.

@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Data structures

Add per-project source-link metadata to component and service records so downstream document generation can distinguish recognized repositories from arbitrary projects.

  • tools/BootstrapBlazor.LLMsDocsGenerator/ComponentInfo.cs L69-70

API

Replace the root/core-only command options with a project selector and direct output-directory option for single-project generation.

  • tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs L17-22, L39-44 (+3 small edits)

Implementation

Adapt Roslyn analysis and document generation to discover components and services in one project, classify source paths, validate output names, and emit per-project indexes and type files.

  • tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs L57-63, L292-302, L1099-1110 (+13 small edits)
  • tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs L11-63, L72-91 (+3 small edits)
  • tools/BootstrapBlazor.LLMsDocsGenerator/MarkdownBuilder.cs L90-95 (+8 small edits)

Configuration

Update the tool package project configuration for the 11.0.3 release and its package metadata.

  • tools/BootstrapBlazor.LLMsDocsGenerator/BootstrapBlazor.LLMsDocsGenerator.csproj L4, L13-14

Documentation

Rewrite the English and Chinese usage guides to describe single-project invocation, output layout, analysis limitations, and validation steps.

  • tools/BootstrapBlazor.LLMsDocsGenerator/README.md L5-23, L28-94, L96 (removed lines)
  • tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md L5-23, L28-94

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@bb-auto bb-auto Bot added the enhancement New feature or request label Nov 17, 2026
@bb-auto bb-auto Bot added this to the v11.0.0 milestone Nov 17, 2026

@bb-auto bb-auto Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto approved by bb-auto

@ArgoZhang
ArgoZhang merged commit 143425d into master Nov 17, 2026
3 checks passed
@ArgoZhang
ArgoZhang deleted the dev-skill-nuget branch November 17, 2026 00:44
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Linked issues

Checked at commit 8fd5d58

#1314 feat(LLMsDocsGenerator): generate documentation per project · 6 of 6 met

# Requirement Status Notes
1 Generate documentation for the current project by default ✅ Met When --project is omitted, the generator uses the current working directory.
2 Allow selecting a project with --project ✅ Met --project accepts a project file or directory, and the generator validates that the selected directory contains exactly one .csproj.
3 Remove --root and --core-only and website-wide generation ✅ Met The CLI and generation flow use project-local analysis instead of the former repository-wide and core-only modes.
4 Discover local components and services ✅ Met Single-project analysis scans the selected project source for components and service types.
5 Update both READMEs ✅ Met Both the English and Chinese guides describe single-project usage, options, output, and analysis limitations.
6 Release 11.0.3 with license and readme package metadata ✅ Met The project metadata sets version 11.0.3, Apache-2.0 licensing, and README.md as the package readme.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 13 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="61" />
<code_context>
         _sourcePath = sourcePath;
-        _componentsPath = Path.Combine(sourcePath, "Components");
+        _singleProject = singleProject;
+        _componentsPath = singleProject ? sourcePath : Path.Combine(sourcePath, "Components");
+        _extensionRepository = singleProject
+            ? FindExtensionRepository(sourcePath) : null;
</code_context>
<issue_to_address>
**Non-components appear as components**

When the project contains a matching entry file whose class is not a component, `AnalyzeAllComponentsAsync` passes matching files to `AnalyzeEntryFile` without checking `IsComponentType`, and the `_singleProject` condition 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 `IsComponentType` before adding them to the component list.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:102`.
</issue_to_address>

### Comment 2
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="61" />
<code_context>
         _sourcePath = sourcePath;
-        _componentsPath = Path.Combine(sourcePath, "Components");
+        _singleProject = singleProject;
+        _componentsPath = singleProject ? sourcePath : Path.Combine(sourcePath, "Components");
+        _extensionRepository = singleProject
+            ? FindExtensionRepository(sourcePath) : null;
</code_context>
<issue_to_address>
**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.
</issue_to_address>

### Comment 3
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="21" />
<code_context>
-            throw new DirectoryNotFoundException($"Core source directory not found: {_sourcePath}");
+            throw new InvalidDataException($"Expected one project in {sourcePath}, found {projectFiles.Length}.");
         }
+        var packageName = Path.GetFileNameWithoutExtension(projectFiles[0]);

+        Logger($"Source path: {sourcePath}");
</code_context>
<issue_to_address>
**Install command names wrong package**

When the project declares a `PackageId` different from its `.csproj` filename or is not published as a package, `GenerateAllAsync` derives `packageName` from the project filename, and `BuildIndexDoc` prints it as the NuGet package ID. The generated install command therefore names the wrong package or a package that is not published.

Use the declared `PackageId` for the install command and omit or otherwise handle the command when the project is not published as a package.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/MarkdownBuilder.cs:102`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:22`.
</issue_to_address>

### Comment 4
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="16" />
<code_context>
-
-        if (!Directory.Exists(_sourcePath))
+        var sourcePath = GetSourcePath(project);
+        var projectFiles = Directory.GetFiles(sourcePath, "*.csproj");
+        if (projectFiles.Length != 1)
         {
</code_context>
<issue_to_address>
**Selected project is rejected**

When `--project` names a `.csproj` in a directory containing another `.csproj`, `GetSourcePath` reduces the selection to its directory, then `GenerateAllAsync` requires that directory to contain exactly one project. The requested project is rejected instead of analyzed.

Preserve and analyze the explicitly selected `.csproj` rather than requiring its directory to contain exactly one project.
</issue_to_address>

### Comment 5
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="58" />
<code_context>
         Logger($"Generated: {indexPath}");

-        var componentsOutputPath = Path.Combine(_outputPath, "components");
+        var componentsOutputPath = Path.Combine(outputFolder, "components");
         Directory.CreateDirectory(componentsOutputPath);
-        foreach (var component in components)
</code_context>
<issue_to_address>
**Generated docs overwrite source files**

When the default output is used on a case-insensitive filesystem and the project has a `Components` directory, `componentsOutputPath` aliases the project's `Components` directory, so generated documentation is placed among authored sources; same-named `.txt` files can be overwritten, and stale-file cleanup can delete marked files there.

Ensure the default documentation output directory cannot alias the project's `Components` source directory.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:61`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:59`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:129`.
</issue_to_address>

### Comment 6
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="55" />
<code_context>
-        await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly));
+        Directory.CreateDirectory(outputFolder);
+        var indexPath = Path.Combine(outputFolder, "llms.txt");
+        await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, "zh", packageName));
         Logger($"Generated: {indexPath}");

</code_context>
<issue_to_address>
**Concurrent runs leave broken output**

When two invocations targeting the same output directory overlap, each invocation writes its index and component files and then cleans stale files based on its own type set. One run can delete files written by the other, leaving an index with missing links or mixed documentation.

Serialize writes and stale-file cleanup for each output directory, or publish each complete run atomically.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:54`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:62`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:64`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:67`.
</issue_to_address>

### Comment 7
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="55" />
<code_context>
-        await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly));
+        Directory.CreateDirectory(outputFolder);
+        var indexPath = Path.Combine(outputFolder, "llms.txt");
+        await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, "zh", packageName));
         Logger($"Generated: {indexPath}");

</code_context>
<issue_to_address>
**Interrupted writes leave inconsistent docs**

When the process stops or a file write fails after the index or some type files have been written, `GenerateAllAsync` writes the index before all component documents are complete, so an interrupted run leaves a new index alongside missing or old documents. Readers see an inconsistent documentation set.

Write the complete documentation set to a staging location and publish it only after all writes succeed.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:54`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:62`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:64`.
</issue_to_address>

### Comment 8
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="62" />
<code_context>
         {
-            var content = MarkdownBuilder.BuildComponentDoc(service, "zh");
-            var filePath = Path.Combine(componentsOutputPath, $"{service.Name}.txt");
+            var content = MarkdownBuilder.BuildComponentDoc(type, "zh");
+            var filePath = Path.Combine(componentsOutputPath, $"{type.Name}.txt");
             await File.WriteAllTextAsync(filePath, content);
</code_context>
<issue_to_address>
**Type pages show wrong library**

When the selected project is not BootstrapBlazor, `GenerateAllAsync` calls `BuildComponentDoc` without the target project name, and `BuildComponentDoc` uses the fixed `BootstrapBlazor` heading. Generated component and service pages therefore identify another project's APIs as BootstrapBlazor APIs.

Pass the target project identity to `BuildComponentDoc` and use it in the page heading.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:63`.
</issue_to_address>

### Comment 9
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="723" />
<code_context>
             BaseClass = GetBaseClassName(symbol),
             SourcePath = GetRelativePath(filePath),
+            IsExtension = _singleProject && _extensionRepository != null,
+            SuppressSourceLink = _singleProject && _extensionRepository == null,
             LastModified = File.GetLastWriteTimeUtc(filePath),
             SamplePath = FindSamplePath(symbol.Name),
</code_context>
<issue_to_address>
**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`.
</issue_to_address>

### Comment 10
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="67" />
<code_context>
-            Logger($"Generated {extComponents.Count + extServices.Count} extension files in {extOutputPath}");
-        }
-
         RemoveStaleDocuments(componentsOutputPath, components.Concat(services));
-        RemoveStaleDocuments(Path.Combine(_outputPath, "extensions"), extComponents.Concat(extServices));

</code_context>
<issue_to_address>
**Old extension documents remain**

When the output directory contains generated extension documents from an earlier run, `RemoveStaleDocuments` cleans only `components/` and no longer removes marked files from `extensions/`. Those obsolete documents remain in the output tree after the index stops listing them.

Remove stale generated documents from the former `extensions/` output directory as well.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:160`.
</issue_to_address>

### Comment 11
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="596" />
<code_context>
     {
         var content = await File.ReadAllTextAsync(razorFile);
+        if (_singleProject && (Path.GetFileName(razorFile).StartsWith('_') ||
+            content.Split('\n').Any(line => line.TrimStart().StartsWith("@page ", StringComparison.Ordinal))))
+        {
+            return null;
</code_context>
<issue_to_address>
**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.
</issue_to_address>

### Comment 12
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="595-598" />
<code_context>
     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))))
+        {
+            return null;
+        }

</code_context>
<issue_to_address>
**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.
</issue_to_address>

### Comment 13
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/README.md" line_range="94" />
<code_context>
-- Modal: https://www.blazor.zone/llms/components/Modal.txt
+```powershell
+dotnet build .\tools\BootstrapBlazor.LLMsDocsGenerator -c Release
+.\tools\BootstrapBlazor.LLMsDocsGenerator\tests\Verify-SingleProject.ps1
 ```
-
</code_context>
<issue_to_address>
**Validation command references absent script**

When A contributor follows the documented PowerShell validation steps from the repository root, the documented validation command invokes `tests\Verify-SingleProject.ps1`, but that script is not included in the tracked changes, so following the README instructions fails with a file-not-found error.

Include the referenced script in the PR or remove the command and describe only the validation steps available in the checkout.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md:94`.
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_sourcePath = sourcePath;
_componentsPath = Path.Combine(sourcePath, "Components");
_singleProject = singleProject;
_componentsPath = singleProject ? sourcePath : Path.Combine(sourcePath, "Components");

Copy link
Copy Markdown

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, AnalyzeAllComponentsAsync passes matching files to AnalyzeEntryFile without checking IsComponentType, and the _singleProject condition 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 IsComponentType before adding them to the component list.

Also at tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:102.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at line 61:

**Non-components appear as components**

When the project contains a matching entry file whose class is not a component, `AnalyzeAllComponentsAsync` passes matching files to `AnalyzeEntryFile` without checking `IsComponentType`, and the `_singleProject` condition 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 `IsComponentType` before adding them to the component list.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:102`.

_sourcePath = sourcePath;
_componentsPath = Path.Combine(sourcePath, "Components");
_singleProject = singleProject;
_componentsPath = singleProject ? sourcePath : Path.Combine(sourcePath, "Components");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The 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 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.

Prompt for AI agents
In `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.

throw new DirectoryNotFoundException($"Core source directory not found: {_sourcePath}");
throw new InvalidDataException($"Expected one project in {sourcePath}, found {projectFiles.Length}.");
}
var packageName = Path.GetFileNameWithoutExtension(projectFiles[0]);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Install command names wrong package

When the project declares a PackageId different from its .csproj filename or is not published as a package, GenerateAllAsync derives packageName from the project filename, and BuildIndexDoc prints it as the NuGet package ID. The generated install command therefore names the wrong package or a package that is not published.

Use the declared PackageId for the install command and omit or otherwise handle the command when the project is not published as a package.

Also at tools/BootstrapBlazor.LLMsDocsGenerator/MarkdownBuilder.cs:102, tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:22.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 21:

**Install command names wrong package**

When the project declares a `PackageId` different from its `.csproj` filename or is not published as a package, `GenerateAllAsync` derives `packageName` from the project filename, and `BuildIndexDoc` prints it as the NuGet package ID. The generated install command therefore names the wrong package or a package that is not published.

Use the declared `PackageId` for the install command and omit or otherwise handle the command when the project is not published as a package.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/MarkdownBuilder.cs:102`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:22`.


if (!Directory.Exists(_sourcePath))
var sourcePath = GetSourcePath(project);
var projectFiles = Directory.GetFiles(sourcePath, "*.csproj");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Selected project is rejected

When --project names a .csproj in a directory containing another .csproj, GetSourcePath reduces the selection to its directory, then GenerateAllAsync requires that directory to contain exactly one project. The requested project is rejected instead of analyzed.

Preserve and analyze the explicitly selected .csproj rather than requiring its directory to contain exactly one project.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 16:

**Selected project is rejected**

When `--project` names a `.csproj` in a directory containing another `.csproj`, `GetSourcePath` reduces the selection to its directory, then `GenerateAllAsync` requires that directory to contain exactly one project. The requested project is rejected instead of analyzed.

Preserve and analyze the explicitly selected `.csproj` rather than requiring its directory to contain exactly one project.

Logger($"Generated: {indexPath}");

var componentsOutputPath = Path.Combine(_outputPath, "components");
var componentsOutputPath = Path.Combine(outputFolder, "components");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Generated docs overwrite source files

When the default output is used on a case-insensitive filesystem and the project has a Components directory, componentsOutputPath aliases the project's Components directory, so generated documentation is placed among authored sources; same-named .txt files can be overwritten, and stale-file cleanup can delete marked files there.

Ensure the default documentation output directory cannot alias the project's Components source directory.

Also at tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:61, tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:59, tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:129.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 58:

**Generated docs overwrite source files**

When the default output is used on a case-insensitive filesystem and the project has a `Components` directory, `componentsOutputPath` aliases the project's `Components` directory, so generated documentation is placed among authored sources; same-named `.txt` files can be overwritten, and stale-file cleanup can delete marked files there.

Ensure the default documentation output directory cannot alias the project's `Components` source directory.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs:61`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:59`, `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:129`.

BaseClass = GetBaseClassName(symbol),
SourcePath = GetRelativePath(filePath),
IsExtension = _singleProject && _extensionRepository != null,
SuppressSourceLink = _singleProject && _extensionRepository == null,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The 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, 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.

Prompt for AI agents
In `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`.

Logger($"Generated {extComponents.Count + extServices.Count} extension files in {extOutputPath}");
}

RemoveStaleDocuments(componentsOutputPath, components.Concat(services));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Old extension documents remain

When the output directory contains generated extension documents from an earlier run, RemoveStaleDocuments cleans only components/ and no longer removes marked files from extensions/. Those obsolete documents remain in the output tree after the index stops listing them.

Remove stale generated documents from the former extensions/ output directory as well.

Also at tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:160.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 67:

**Old extension documents remain**

When the output directory contains generated extension documents from an earlier run, `RemoveStaleDocuments` cleans only `components/` and no longer removes marked files from `extensions/`. Those obsolete documents remain in the output tree after the index stops listing them.

Remove stale generated documents from the former `extensions/` output directory as well.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs:160`.

{
var content = await File.ReadAllTextAsync(razorFile);
if (_singleProject && (Path.GetFileName(razorFile).StartsWith('_') ||
content.Split('\n').Any(line => line.TrimStart().StartsWith("@page ", StringComparison.Ordinal))))

Copy link
Copy Markdown

Choose a reason for hiding this comment

The 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 @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.

Prompt for AI agents
In `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.

Comment on lines +595 to +598
if (_singleProject && (Path.GetFileName(razorFile).StartsWith('_') ||
content.Split('\n').Any(line => line.TrimStart().StartsWith("@page ", StringComparison.Ordinal))))
{
return null;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The 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 .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.

Prompt for AI agents
In `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.

- Modal: https://www.blazor.zone/llms/components/Modal.txt
```powershell
dotnet build .\tools\BootstrapBlazor.LLMsDocsGenerator -c Release
.\tools\BootstrapBlazor.LLMsDocsGenerator\tests\Verify-SingleProject.ps1

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ Low · Validation command references absent script

When A contributor follows the documented PowerShell validation steps from the repository root, the documented validation command invokes tests\Verify-SingleProject.ps1, but that script is not included in the tracked changes, so following the README instructions fails with a file-not-found error.

Include the referenced script in the PR or remove the command and describe only the validation steps available in the checkout.

Also at tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md:94.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/README.md` at line 94:

**Validation command references absent script**

When A contributor follows the documented PowerShell validation steps from the repository root, the documented validation command invokes `tests\Verify-SingleProject.ps1`, but that script is not included in the tracked changes, so following the README instructions fails with a file-not-found error.

Include the referenced script in the PR or remove the command and describe only the validation steps available in the checkout.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md:94`.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(LLMsDocsGenerator): generate documentation per project

1 participant