diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs b/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs index a118d615..80272669 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs @@ -19,14 +19,19 @@ public static ParseResult Parse(string[] args) }; var outputFolderOption = new Option("--output") { - Description = "Set the publish folder of project", + Description = "Set the output folder (core-only writes directly; default writes to wwwroot/llms)", DefaultValueFactory = _ => defaultFolder }; + var coreOnlyOption = new Option("--core-only") + { + Description = "Generate only core components and services for BootstrapBlazor packaging, without extension sources" + }; var rootCommand = new RootCommand("BootstrapBlazor LLMs Documentation Generator") { rootFolderOption, - outputFolderOption + outputFolderOption, + coreOnlyOption }; rootCommand.SetAction(async result => @@ -40,10 +45,10 @@ public static ParseResult Parse(string[] args) var outputFolder = result.GetValue(outputFolderOption); if (string.IsNullOrEmpty(outputFolder)) { - throw new ArgumentException("Publish folder must not be empty."); + throw new ArgumentException("Output folder must not be empty."); } - await DocsGenerator.GenerateAllAsync(rootFolder, outputFolder); + await DocsGenerator.GenerateAllAsync(rootFolder, outputFolder, result.GetValue(coreOnlyOption)); }); return rootCommand.Parse(args); diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/BootstrapBlazor.LLMsDocsGenerator.csproj b/tools/BootstrapBlazor.LLMsDocsGenerator/BootstrapBlazor.LLMsDocsGenerator.csproj index 9fcdcff4..74aebb73 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/BootstrapBlazor.LLMsDocsGenerator.csproj +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/BootstrapBlazor.LLMsDocsGenerator.csproj @@ -1,7 +1,7 @@  - 11.0.0 + 11.0.1 Exe false diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs b/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs index 94a16626..f7c9d4bb 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs @@ -12,10 +12,10 @@ internal static class DocsGenerator /// /// Generate all documentation files /// - 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"); Logger($"Source path: {_sourcePath}"); Logger($"Output path: {_outputPath}"); @@ -31,7 +31,7 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder // /.. / 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."); + } - var configuredPackages = provider.ParseExtensions(); + var configuredPackages = coreOnly ? new List() : provider.ParseExtensions(); if (!hasExtensions && configuredPackages.Count > 0) { throw new DirectoryNotFoundException($"Extension sources required by docs.json were not found: {extensionsSrc}"); diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/README.md b/tools/BootstrapBlazor.LLMsDocsGenerator/README.md index c4522a70..175f32ca 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/README.md +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/README.md @@ -25,7 +25,7 @@ AI coding assistants (Claude Code, Cursor, GitHub Copilot) often generate incorr │ ▼ ┌─────────────────────────────────────────────────────────────┐ -│ Output: /wwwroot/llms/ │ +│ Default 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 `` 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 `/../BootstrapBlazor`. | -| `--output` | No | Publish folder. Defaults to `.`. Documentation is written to `/wwwroot/llms/`. | +| `--output` | No | Output folder. Defaults to `.`. Default mode writes to `/wwwroot/llms/`; `--core-only` writes directly to `/`. | +| `--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 `` 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 `` 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 `/llms.txt` and `/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 `` 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: ```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: diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md b/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md index 126c2f7c..e2c3b6d5 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md @@ -25,7 +25,7 @@ AI 编程助手(Claude Code、Cursor、GitHub Copilot)经常因为缺乏准 │ ▼ ┌─────────────────────────────────────────────────────────────┐ -│ 输出目录: /wwwroot/llms/ │ +│ 默认输出目录: /wwwroot/llms/ │ ├─────────────────────────────────────────────────────────────┤ │ llms.txt → 索引文件,包含快速入门指南 │ │ components/ → 单独的组件文档目录 │ @@ -39,6 +39,8 @@ AI 编程助手(Claude Code、Cursor、GitHub Copilot)经常因为缺乏准 └─────────────────────────────────────────────────────────────┘ ``` +使用 `--core-only` 时,输出目录为 `` 本身。 + ### 为什么每个组件单独一个文件? 这种设计针对 LLM 和 Code Agent 进行了优化: @@ -85,7 +87,7 @@ AI 编程助手(Claude Code、Cursor、GitHub Copilot)经常因为缺乏准 ## 环境要求 - 与工程 `TargetFrameworks` 匹配的 SDK(当前源码构建使用 .NET 11)。 -- 本地 `BootstrapBlazor` 仓库;`docs.json` 配置了扩展包时,还需要同级的 `BootstrapBlazor.Extensions` 仓库。生成器不会自动克隆仓库。 +- 本地 `BootstrapBlazor` 仓库;未使用 `--core-only` 且 `docs.json` 配置了扩展包时,还需要同级的 `BootstrapBlazor.Extensions` 仓库。生成器不会自动克隆仓库。 ## 安装 @@ -117,21 +119,24 @@ dotnet tool uninstall --global BootstrapBlazor.LLMsDocsGenerator ## 使用方法 -两个参数均可省略,各自默认为当前工作目录(`.`)。在 BB 的 `src/BootstrapBlazor.Server` 目录直接执行 `llms-docs` 即可将文档生成到该工程。覆盖 `--root` 不会改变 `--output` 的默认值;使用其他仓库或发布目录时请分别指定。 +两个路径参数各自默认为当前工作目录(`.`)。在 BB 的 `src/BootstrapBlazor.Server` 目录直接执行 `llms-docs` 即可将文档生成到该工程。使用 `--core-only` 时,输出直接写入 `--output` 目录,不会清空已有内容。覆盖 `--root` 不会改变 `--output` 的默认值;使用其他仓库或发布目录时请分别指定。 在 Server 工程目录运行时也支持 `dotnet llms-docs --output=bin\Release\publish\`,省略的 `--root` 使用 `.`,相对输出路径也基于当前 Server 目录解析。MSBuild 中可使用 `dotnet llms-docs --output=$(PublishDir)`(路径不含空格时)。 | 选项 | 必需 | 说明 | |------|------|------| | `--root` | 否 | 项目根目录,默认为 `.`。组件源码从 `/../BootstrapBlazor` 读取。 | -| `--output` | 否 | 发布目录,默认为 `.`。文档生成到 `/wwwroot/llms/`。 | +| `--output` | 否 | 输出目录,默认为 `.`。默认模式生成到 `/wwwroot/llms/`;`--core-only` 直接生成到 `/`。 | +| `--core-only` | 否 | 用于 BootstrapBlazor 打包,仅生成核心组件与内置服务文档。默认为 `false`,启用后不分析扩展配置与源码。 | 当 `BootstrapBlazor.Extensions` 仓库与核心 `BootstrapBlazor` 仓库并列存在时,生成器也会分析扩展仓库源码。需在 `src/BootstrapBlazor.Server/docs.json` 的 `extensions` 节中配置要生成文档的扩展包和类型;这是唯一配置位置,文件不存在时生成失败。扩展文档会写入 `extensions/` 目录。 -仅扫描 `BootstrapBlazor.Extensions.slnx` 中列出的源码工程,按工程文件名而非目录名匹配扩展包。配置中不属于解决方案的包会输出提示并跳过;解决方案引用了不存在的工程时会报错。磁盘上残留的其他目录不会参与分析。核心库中仅有 `.razor` 文件、通过 `@inherits` 指定基类的组件也支持生成文档。重新生成时会清理带有 `` 标记的过期 `.txt` 文档,保留其他文件。 +仅扫描 `BootstrapBlazor.Extensions.slnx` 中列出的源码工程,按工程文件名而非目录名匹配扩展包。配置中不属于解决方案的包会输出提示并跳过;解决方案引用了不存在的工程时会报错。磁盘上残留的其他目录不会参与分析。核心库中仅有 `.razor` 文件、通过 `@inherits` 指定基类的组件也支持生成文档。默认模式重新生成时会清理带有 `` 标记的过期 `.txt` 文档,保留其他文件。 配置了扩展包但缺少同级扩展源码仓库时,生成会失败且不改动已有文档。配置中的组件或服务类型无法解析时,也会在写入文件、清理过期文档之前报错。多个包共用的服务接口仍使用一份文档,按配置的包分别列出注册方法,使用时选择对应包的注册方式。 +使用 `--core-only` 时,无需修改 `docs.json`,生成器会忽略 `extensions` 节;无需扩展仓库或解决方案,即使存在也不会读取。核心分类与内置服务仍从 `docs.json` 获取,因此该文件仍为必需。不生成扩展文档、扩展索引章节或链接;扩展也提供的服务仍保留核心服务文档。输出为 `/llms.txt` 与 `/components/*.txt`,索引使用适合包内引用的相对链接。不存在的输出目录会自动创建,不会清空已有内容;仅删除带生成器标记的过期文件,无标记文件与子目录会保留。 + 源码工程 `.csproj` 中显式声明的 ``(包括别名和静态导入)会应用到该工程的 C# 文件,不会在合并分析时泄漏到其他工程。 此工具进行源码分析,不执行完整的 MSBuild 求值:不处理条件、属性展开、导入的 `.props`/`.targets` 及 `Using Remove`。纯 Razor 支持仅合成继承声明,不编译 Razor,也不提取 `@code` 块中的成员。 @@ -140,7 +145,7 @@ dotnet tool uninstall --global BootstrapBlazor.LLMsDocsGenerator 生成错误或显式传入空路径时会返回非零进程退出码,便于 MSBuild 和 CI 中止。 -使用 PowerShell 执行集成检查: +使用 PowerShell 7 执行集成检查;脚本会构建工具,并使用隔离源码夹具调用实际 CLI,验证核心打包与完整官网生成: ```powershell .\tools\BootstrapBlazor.LLMsDocsGenerator\tests\Verify-Generation.ps1 @@ -170,6 +175,16 @@ src/BootstrapBlazor.Server/wwwroot/llms/extensions/*.txt dotnet run --project "..\BootstrapBlazor.Extensions\tools\BootstrapBlazor.LLMsDocsGenerator" --root "src\BootstrapBlazor.Server" --output "src\BootstrapBlazor.Server" ``` +### BootstrapBlazor NuGet 打包 + +在 `BootstrapBlazor` 仓库根目录,将核心文档直接生成到 skill 的 references 目录: + +```powershell +dotnet llms-docs --core-only --root "src\BootstrapBlazor.Server" --output "src\BootstrapBlazor\skills\bootstrapblazor\references" +``` + +无需再使用移除扩展配置的暂存 `docs.json`。BootstrapBlazor.Server 发布时不要传 `--core-only`,以保持完整官网索引、核心与扩展文档;原有发布命令及输出路径不变。 + ## CI/CD 集成 将两个仓库检出到同级目录,使用与生成器工程匹配的 SDK。以下步骤假定工作流位于 `dotnetcore/BootstrapBlazor` 仓库;构建发布版本时请固定兼容的 ref: