Repository navigation
feat(LLMsDocsGenerator): support core-only package generation #1299
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 |
|---|---|---|
|
|
@@ -12,10 +12,10 @@ internal static class DocsGenerator | |
| /// <summary> | ||
| /// Generate all documentation files | ||
| /// </summary> | ||
| public static async Task GenerateAllAsync(string rootFolder, string outputFolder) | ||
| public static async Task GenerateAllAsync(string rootFolder, string outputFolder, bool coreOnly = false) | ||
| { | ||
| var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor"); | ||
| var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms"); | ||
| var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms"); | ||
|
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 · Concurrent runs mix generated docs When two core-only invocations target the same output directory while analyzing different source snapshots, both generator processes write the same paths, and Coordinate generation for each output directory so concurrent runs cannot overwrite or clean up one another's files. Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 18:
**Concurrent runs mix generated docs**
When two core-only invocations target the same output directory while analyzing different source snapshots, both generator processes write the same paths, and `RemoveStaleDocuments` removes files based on each run's snapshot. An older run can overwrite newer files or remove files referenced by the newer index, leaving inconsistent package output.
Coordinate generation for each output directory so concurrent runs cannot overwrite or clean up one another's files.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 · Failed generation leaves mixed docs When a write fails or the process stops after the index is written but before all documents and cleanup complete, Write the index and documents to a staging location and publish them only after generation completes successfully. Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 18:
**Failed generation leaves mixed docs**
When a write fails or the process stops after the index is written but before all documents and cleanup complete, `File.WriteAllTextAsync` overwrites files in place, so the new `llms.txt` remains alongside missing, outdated, or mixed-generation documents when generation stops before completion. Consumers see broken links or inconsistent documentation.
Write the index and documents to a staging location and publish them only after generation completes successfully.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 · User-authored files are overwritten When a pre-existing unmarked file occupies a generated path, Check whether an existing file is marked as generated and preserve it when it is unmarked. Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 18:
**User-authored files are overwritten**
When a pre-existing unmarked file occupies a generated path, `File.WriteAllTextAsync` replaces the file without checking its marker, so the user's contents are lost.
Check whether an existing file is marked as generated and preserve it when it is unmarked. |
||
|
|
||
| Logger($"Source path: {_sourcePath}"); | ||
| Logger($"Output path: {_outputPath}"); | ||
|
|
@@ -31,7 +31,7 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder | |
| // <core-repo>/.. / BootstrapBlazor.Extensions / src | ||
| var coreRepoRoot = Path.GetDirectoryName(Path.GetDirectoryName(Path.GetFullPath(_sourcePath)))!; | ||
| var extensionsSrc = Path.Combine(Path.GetDirectoryName(coreRepoRoot)!, "BootstrapBlazor.Extensions", "src"); | ||
| var hasExtensions = Directory.Exists(extensionsSrc); | ||
| var hasExtensions = !coreOnly && Directory.Exists(extensionsSrc); | ||
|
|
||
| var extensionProjects = hasExtensions | ||
| ? ReadExtensionProjects(Path.GetDirectoryName(extensionsSrc)!) | ||
|
|
@@ -40,6 +40,10 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder | |
| extensionProjects); | ||
| var components = await _analyzer.AnalyzeAllComponentsAsync(); | ||
| Logger($"Found {components.Count} components"); | ||
| if (components.Count == 0) | ||
| { | ||
| throw new InvalidDataException("No core components found."); | ||
| } | ||
|
|
||
| // Derive index categories, injected services and extension packages from docs.json. | ||
| var serverPath = Path.Combine(Path.GetDirectoryName(Path.GetFullPath(_sourcePath))!, "BootstrapBlazor.Server"); | ||
|
|
@@ -48,8 +52,12 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder | |
| Logger($"Found {categories.Count} categories"); | ||
| var services = await _analyzer.AnalyzeServicesAsync(provider.ParseServices()); | ||
| Logger($"Found {services.Count} services"); | ||
| if (services.Count == 0) | ||
| { | ||
| throw new InvalidDataException("No core services found."); | ||
| } | ||
|
Comment on lines
+55
to
+58
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 · Website generation rejects empty services When Apply the nonempty-services validation only in core-only mode, or allow empty services in default mode. Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at lines 55-58:
**Website generation rejects empty services**
When `docs.json` omits `services` or configures it as an empty array, the unconditional check throws `InvalidDataException` before writing documentation, so otherwise valid default website generation fails instead of producing an index without a services section.
Apply the nonempty-services validation only in core-only mode, or allow empty services in default mode. |
||
|
|
||
| var configuredPackages = provider.ParseExtensions(); | ||
| var configuredPackages = coreOnly ? new List<ExtensionPackage>() : provider.ParseExtensions(); | ||
| if (!hasExtensions && configuredPackages.Count > 0) | ||
| { | ||
| throw new DirectoryNotFoundException($"Extension sources required by docs.json were not found: {extensionsSrc}"); | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -25,7 +25,7 @@ AI coding assistants (Claude Code, Cursor, GitHub Copilot) often generate incorr | |
| │ | ||
| ▼ | ||
| ┌─────────────────────────────────────────────────────────────┐ | ||
| │ Output: <output>/wwwroot/llms/ │ | ||
| │ Default output: <output>/wwwroot/llms/ │ | ||
| ├─────────────────────────────────────────────────────────────┤ | ||
| │ llms.txt → Index with quick start guide │ | ||
| │ components/ → Individual component documentation │ | ||
|
|
@@ -39,6 +39,8 @@ AI coding assistants (Claude Code, Cursor, GitHub Copilot) often generate incorr | |
| └─────────────────────────────────────────────────────────────┘ | ||
| ``` | ||
|
|
||
| With `--core-only`, the output directory is `<output>` itself. | ||
|
|
||
| ### Why One File Per Component? | ||
|
|
||
| This design optimizes for LLM and Code Agent consumption: | ||
|
|
@@ -85,7 +87,7 @@ Components are organized in the index by category for easy navigation, but each | |
| ## Requirements | ||
|
|
||
| - An SDK matching the project's `TargetFrameworks` (currently .NET 11 for source builds). | ||
| - A local `BootstrapBlazor` checkout; when `docs.json` configures extension packages, also check out `BootstrapBlazor.Extensions` beside it. The generator does not clone repositories. | ||
| - A local `BootstrapBlazor` checkout; unless using `--core-only`, when `docs.json` configures extension packages, also check out `BootstrapBlazor.Extensions` beside it. The generator does not clone repositories. | ||
|
|
||
| ## Installation | ||
|
|
||
|
|
@@ -117,21 +119,24 @@ Once installed, the tool is invoked with the command name `llms-docs`. | |
|
|
||
| ## Usage | ||
|
|
||
| Both options are optional and independently default to the current working directory (`.`). Run `llms-docs` without arguments from BB's `src/BootstrapBlazor.Server` directory to write documentation into that project. Overriding `--root` does not change the default `--output`; specify both when using another checkout or publish directory. | ||
| Both path options independently default to the current working directory (`.`). Run `llms-docs` without arguments from BB's `src/BootstrapBlazor.Server` directory to write documentation into that project. With `--core-only`, output is written directly to the `--output` directory without clearing existing contents. Overriding `--root` does not change the default `--output`; specify both when using another checkout or publish directory. | ||
|
|
||
| From the Server project directory, `dotnet llms-docs --output=bin\Release\publish\` also works: the omitted `--root` defaults to `.`, and relative output paths are resolved from that same directory. MSBuild can use `dotnet llms-docs --output=$(PublishDir)` when the path contains no spaces. | ||
|
|
||
| | Option | Required | Description | | ||
| |--------|----------|-------------| | ||
| | `--root` | No | Project root folder. Defaults to `.`. Component source is read from `<root>/../BootstrapBlazor`. | | ||
| | `--output` | No | Publish folder. Defaults to `.`. Documentation is written to `<output>/wwwroot/llms/`. | | ||
| | `--output` | No | Output folder. Defaults to `.`. Default mode writes to `<output>/wwwroot/llms/`; `--core-only` writes directly to `<output>/`. | | ||
| | `--core-only` | No | Generate only core components and built-in services for BootstrapBlazor packaging. Defaults to `false`; extension configuration and sources are not analyzed. | | ||
|
|
||
| When a `BootstrapBlazor.Extensions` checkout is available beside the core `BootstrapBlazor` checkout, the generator also analyzes the extension sources. The extension types to document are configured under `extensions` in `src/BootstrapBlazor.Server/docs.json`, the only configuration location. Generation fails if the file is missing. Extension docs are written to `extensions/`. | ||
|
|
||
| Only source projects listed in `BootstrapBlazor.Extensions.slnx` are scanned. Package names are matched against project filenames, not directory names. Configured packages outside the solution are skipped with a diagnostic; missing solution projects are reported as errors. Leftover directories do not participate in analysis. Core Razor-only components with an `@inherits` directive are also supported. Regeneration removes obsolete `.txt` files carrying the generator's `<!-- Generated: ... -->` marker, while preserving other files. | ||
| Only source projects listed in `BootstrapBlazor.Extensions.slnx` are scanned. Package names are matched against project filenames, not directory names. Configured packages outside the solution are skipped with a diagnostic; missing solution projects are reported as errors. Leftover directories do not participate in analysis. Core Razor-only components with an `@inherits` directive are also supported. In default mode, regeneration removes obsolete `.txt` files carrying the generator's `<!-- Generated: ... -->` marker, while preserving other files. | ||
|
|
||
| If extension packages are configured but the sibling extension source checkout is missing, generation fails before changing existing documentation. Unresolved configured component or service types also fail generation before writing files or removing stale documents. Services shared by multiple packages retain one document listing the registration method for each configured package; choose the registration matching the package in use. | ||
|
|
||
| With `--core-only`, the `extensions` section is ignored without editing `docs.json`, and no extension checkout or solution is required or read, even when present. Core categories and services still come from `docs.json`, which remains required. No extension documents or extension index sections/links are generated; services also provided by extensions remain in the core service documentation. The output is `<output>/llms.txt` and `<output>/components/*.txt`, with relative index links suitable for a package. The output directory is created if needed; existing contents are not cleared. Stale files carrying the generator marker are removed while unmarked files and subdirectories are preserved. | ||
|
|
||
| Explicit `<Using Include="..." />` items in each source project's `.csproj` (including aliases and static imports) are applied to that project's C# files, without leaking these imports into other projects in the combined analysis. | ||
|
|
||
| This is source analysis, not a full MSBuild evaluation: conditions, property expansion, imported `.props`/`.targets`, and `Using Remove` are not evaluated. Razor-only support synthesizes inheritance declarations; it does not compile Razor or extract members from `@code` blocks. | ||
|
|
@@ -140,7 +145,7 @@ Declare extension services by the types actually registered for injection. For e | |
|
|
||
| Generation errors and explicitly empty paths return a nonzero process exit code so MSBuild and CI can stop. | ||
|
|
||
| Run the integration checks with PowerShell: | ||
| Run the integration checks with PowerShell 7. They build the tool and invoke its actual CLI against isolated source fixtures for core-only packaging and full website generation: | ||
|
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. ⚪ Low · Documented verification script is missing When a reader tries to run the documented integration checks, readers following the stated integration-check instructions run Add the referenced verification script, or remove the claims and command from both READMEs until it exists. Also at Prompt for AI agentsIn `tools/BootstrapBlazor.LLMsDocsGenerator/README.md` at line 148:
**Documented verification script is missing**
When a reader tries to run the documented integration checks, readers following the stated integration-check instructions run `tools/BootstrapBlazor.LLMsDocsGenerator/tests/Verify-Generation.ps1`, but that script and the `tests` directory are absent, so the documented core-only and website verification cannot run.
Add the referenced verification script, or remove the claims and command from both READMEs until it exists.
Also at `tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md:148`. |
||
|
|
||
| ```powershell | ||
| .\tools\BootstrapBlazor.LLMsDocsGenerator\tests\Verify-Generation.ps1 | ||
|
|
@@ -170,6 +175,16 @@ From the same `BootstrapBlazor` repository root, run the sibling source project: | |
| dotnet run --project "..\BootstrapBlazor.Extensions\tools\BootstrapBlazor.LLMsDocsGenerator" --root "src\BootstrapBlazor.Server" --output "src\BootstrapBlazor.Server" | ||
| ``` | ||
|
|
||
| ### BootstrapBlazor NuGet packaging | ||
|
|
||
| From the `BootstrapBlazor` repository root, generate core-only documentation directly into the skill references directory: | ||
|
|
||
| ```powershell | ||
| dotnet llms-docs --core-only --root "src\BootstrapBlazor.Server" --output "src\BootstrapBlazor\skills\bootstrapblazor\references" | ||
| ``` | ||
|
|
||
| No staging copy of `docs.json` with extensions removed is needed. BootstrapBlazor.Server publishing must omit `--core-only` to keep the full website index, core documentation and extension documentation; its existing command and output paths are unchanged. | ||
|
|
||
| ## CI/CD Integration | ||
|
|
||
| Check out both repositories as siblings and use an SDK matching the checked-out generator project. The following steps assume the workflow belongs to `dotnetcore/BootstrapBlazor`; pin compatible refs when building a release: | ||
|
|
||
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 · Symlinked outputs overwrite targets
When the output tree contains a symlink at a generated filename pointing to another writable file, a contributor who controls the core-only output tree can place a symlink at
llms.txtor a generated component filename; the subsequentFile.WriteAllTextAsyncfollows it and overwrites the symlink target, including files outside the output tree that the generator can write.Reject symlinked generated destinations and symlinked output subdirectories before writing.
Prompt for AI agents