From e877ddc452527cddd14c2c7b254d8ca31868e811 Mon Sep 17 00:00:00 2001 From: Argo Zhang Date: Fri, 13 Nov 2026 16:01:28 +0800 Subject: [PATCH 1/4] =?UTF-8?q?feat:=20=E5=A2=9E=E5=8A=A0=20core=20only=20?= =?UTF-8?q?=E5=BC=80=E5=85=B3=E5=8F=82=E6=95=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../ArgumentsHelper.cs | 9 +++++++-- .../DocsGenerator.cs | 6 +++--- .../README.md | 19 ++++++++++++++++--- .../README.zh-CN.md | 19 ++++++++++++++++--- 4 files changed, 42 insertions(+), 11 deletions(-) diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs b/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs index a118d615..01a86c8b 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs @@ -22,11 +22,16 @@ public static ParseResult Parse(string[] args) Description = "Set the publish folder of project", 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 => @@ -43,7 +48,7 @@ public static ParseResult Parse(string[] args) throw new ArgumentException("Publish 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/DocsGenerator.cs b/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs index 94a16626..15e0d372 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs @@ -12,7 +12,7 @@ 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"); @@ -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)!) @@ -49,7 +49,7 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder var services = await _analyzer.AnalyzeServicesAsync(provider.ParseServices()); Logger($"Found {services.Count} services"); - 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..2f35fb45 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/README.md +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/README.md @@ -85,7 +85,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,7 +117,7 @@ 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 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. 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. @@ -125,6 +125,7 @@ From the Server project directory, `dotnet llms-docs --output=bin\Release\publis |--------|----------|-------------| | `--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/`. | +| `--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/`. @@ -132,6 +133,8 @@ Only source projects listed in `BootstrapBlazor.Extensions.slnx` are scanned. Pa 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 layout stays `/wwwroot/llms/llms.txt` and `components/*.txt`, with relative index links suitable for copying into a package. Existing generated extension `.txt` files are removed on regeneration; unmarked files are preserved, so use a dedicated output directory for packaging. + 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 +143,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 +173,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 into a dedicated staging directory: + +```powershell +dotnet llms-docs --core-only --root "src\BootstrapBlazor.Server" --output "artifacts\llms-pack" +``` + +Copy the contents of `artifacts\llms-pack\wwwroot\llms` into `src\BootstrapBlazor\skills\bootstrapblazor\references` for packaging. 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..cffe2371 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md @@ -85,7 +85,7 @@ AI 编程助手(Claude Code、Cursor、GitHub Copilot)经常因为缺乏准 ## 环境要求 - 与工程 `TargetFrameworks` 匹配的 SDK(当前源码构建使用 .NET 11)。 -- 本地 `BootstrapBlazor` 仓库;`docs.json` 配置了扩展包时,还需要同级的 `BootstrapBlazor.Extensions` 仓库。生成器不会自动克隆仓库。 +- 本地 `BootstrapBlazor` 仓库;未使用 `--core-only` 且 `docs.json` 配置了扩展包时,还需要同级的 `BootstrapBlazor.Extensions` 仓库。生成器不会自动克隆仓库。 ## 安装 @@ -117,7 +117,7 @@ dotnet tool uninstall --global BootstrapBlazor.LLMsDocsGenerator ## 使用方法 -两个参数均可省略,各自默认为当前工作目录(`.`)。在 BB 的 `src/BootstrapBlazor.Server` 目录直接执行 `llms-docs` 即可将文档生成到该工程。覆盖 `--root` 不会改变 `--output` 的默认值;使用其他仓库或发布目录时请分别指定。 +两个路径参数均可省略,各自默认为当前工作目录(`.`)。在 BB 的 `src/BootstrapBlazor.Server` 目录直接执行 `llms-docs` 即可将文档生成到该工程。覆盖 `--root` 不会改变 `--output` 的默认值;使用其他仓库或发布目录时请分别指定。 在 Server 工程目录运行时也支持 `dotnet llms-docs --output=bin\Release\publish\`,省略的 `--root` 使用 `.`,相对输出路径也基于当前 Server 目录解析。MSBuild 中可使用 `dotnet llms-docs --output=$(PublishDir)`(路径不含空格时)。 @@ -125,6 +125,7 @@ dotnet tool uninstall --global BootstrapBlazor.LLMsDocsGenerator |------|------|------| | `--root` | 否 | 项目根目录,默认为 `.`。组件源码从 `/../BootstrapBlazor` 读取。 | | `--output` | 否 | 发布目录,默认为 `.`。文档生成到 `/wwwroot/llms/`。 | +| `--core-only` | 否 | 用于 BootstrapBlazor 打包,仅生成核心组件与内置服务文档。默认为 `false`,启用后不分析扩展配置与源码。 | 当 `BootstrapBlazor.Extensions` 仓库与核心 `BootstrapBlazor` 仓库并列存在时,生成器也会分析扩展仓库源码。需在 `src/BootstrapBlazor.Server/docs.json` 的 `extensions` 节中配置要生成文档的扩展包和类型;这是唯一配置位置,文件不存在时生成失败。扩展文档会写入 `extensions/` 目录。 @@ -132,6 +133,8 @@ dotnet tool uninstall --global BootstrapBlazor.LLMsDocsGenerator 配置了扩展包但缺少同级扩展源码仓库时,生成会失败且不改动已有文档。配置中的组件或服务类型无法解析时,也会在写入文件、清理过期文档之前报错。多个包共用的服务接口仍使用一份文档,按配置的包分别列出注册方法,使用时选择对应包的注册方式。 +使用 `--core-only` 时,无需修改 `docs.json`,生成器会忽略 `extensions` 节;无需扩展仓库或解决方案,即使存在也不会读取。核心分类与内置服务仍从 `docs.json` 获取,因此该文件仍为必需。不生成扩展文档、扩展索引章节或链接;扩展也提供的服务仍保留核心服务文档。输出布局仍为 `/wwwroot/llms/llms.txt` 与 `components/*.txt`,索引使用相对链接,可直接复制到包内。重新生成时会清理已有的带生成标记的扩展 `.txt`,保留无标记文件,因此打包请使用独立输出目录。 + 源码工程 `.csproj` 中显式声明的 ``(包括别名和静态导入)会应用到该工程的 C# 文件,不会在合并分析时泄漏到其他工程。 此工具进行源码分析,不执行完整的 MSBuild 求值:不处理条件、属性展开、导入的 `.props`/`.targets` 及 `Using Remove`。纯 Razor 支持仅合成继承声明,不编译 Razor,也不提取 `@code` 块中的成员。 @@ -140,7 +143,7 @@ dotnet tool uninstall --global BootstrapBlazor.LLMsDocsGenerator 生成错误或显式传入空路径时会返回非零进程退出码,便于 MSBuild 和 CI 中止。 -使用 PowerShell 执行集成检查: +使用 PowerShell 7 执行集成检查;脚本会构建工具,并使用隔离源码夹具调用实际 CLI,验证核心打包与完整官网生成: ```powershell .\tools\BootstrapBlazor.LLMsDocsGenerator\tests\Verify-Generation.ps1 @@ -170,6 +173,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` 仓库根目录,将核心文档生成到独立的暂存目录: + +```powershell +dotnet llms-docs --core-only --root "src\BootstrapBlazor.Server" --output "artifacts\llms-pack" +``` + +将 `artifacts\llms-pack\wwwroot\llms` 的内容复制到 `src\BootstrapBlazor\skills\bootstrapblazor\references` 随包分发,无需再使用移除扩展配置的暂存 `docs.json`。BootstrapBlazor.Server 发布时不要传 `--core-only`,以保持完整官网索引、核心与扩展文档;原有发布命令及输出路径不变。 + ## CI/CD 集成 将两个仓库检出到同级目录,使用与生成器工程匹配的 SDK。以下步骤假定工作流位于 `dotnetcore/BootstrapBlazor` 仓库;构建发布版本时请固定兼容的 ref: From 78a156f94659e1733a0617a53691409fd2a3594b Mon Sep 17 00:00:00 2001 From: Argo Zhang Date: Fri, 13 Nov 2026 16:01:49 +0800 Subject: [PATCH 2/4] chore: bump version 11.0.1 --- .../BootstrapBlazor.LLMsDocsGenerator.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 3f3b206c311208a66e0b0374011f82d8c8953289 Mon Sep 17 00:00:00 2001 From: Argo Zhang Date: Sat, 14 Nov 2026 17:01:54 +0800 Subject: [PATCH 3/4] feat(LLMsDocsGenerator): support core-only package output Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../ArgumentsHelper.cs | 4 +- .../DocsGenerator.cs | 97 ++++++++++++++++++- .../README.md | 18 ++-- .../README.zh-CN.md | 18 ++-- 4 files changed, 117 insertions(+), 20 deletions(-) diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs b/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs index 01a86c8b..503e54bf 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs @@ -19,7 +19,7 @@ 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 clears it; default writes to wwwroot/llms)", DefaultValueFactory = _ => defaultFolder }; var coreOnlyOption = new Option("--core-only") @@ -45,7 +45,7 @@ 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, result.GetValue(coreOnlyOption)); diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs b/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs index 15e0d372..662686de 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs @@ -15,7 +15,7 @@ internal static class DocsGenerator 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}"); @@ -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,6 +52,10 @@ 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 = coreOnly ? new List() : provider.ParseExtensions(); if (!hasExtensions && configuredPackages.Count > 0) @@ -88,7 +96,14 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder // Chinese documentation only: the index at the docs root and one file per // component (Chinese text extracted from the bilingual blocks) under // the components/ directory. - Directory.CreateDirectory(_outputPath); + if (coreOnly) + { + PrepareCoreOnlyOutput(_outputPath, _sourcePath, rootFolder); + } + else + { + Directory.CreateDirectory(_outputPath); + } var indexPath = Path.Combine(_outputPath, "llms.txt"); await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh")); Logger($"Generated: {indexPath}"); @@ -129,6 +144,84 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder Logger("Documentation generation complete!"); } + private static void PrepareCoreOnlyOutput(string outputPath, string sourcePath, string rootFolder) + { + var fullOutputPath = Path.TrimEndingDirectorySeparator(Path.GetFullPath(outputPath)); + var expectedSuffix = Path.Combine("skills", "bootstrapblazor", "references"); + if (!EndsWithDirectorySequence(fullOutputPath, expectedSuffix) + || PathContainsSymbolicLink(fullOutputPath)) + { + throw new ArgumentException( + $"Core-only output must be a BootstrapBlazor skill references directory without symbolic links: {fullOutputPath}", + nameof(outputPath)); + } + + var protectedPaths = new[] + { + Directory.GetCurrentDirectory(), + Path.GetFullPath(sourcePath), + Path.GetFullPath(rootFolder) + }; + if (protectedPaths.Any(path => + IsSameOrAncestor(fullOutputPath, Path.TrimEndingDirectorySeparator(Path.GetFullPath(path))))) + { + throw new ArgumentException( + $"Core-only output must not be a working or source directory: {fullOutputPath}", + nameof(outputPath)); + } + + Directory.CreateDirectory(fullOutputPath); + foreach (var entry in Directory.EnumerateFileSystemEntries(fullOutputPath)) + { + var attributes = File.GetAttributes(entry); + if ((attributes & FileAttributes.Directory) != 0) + { + Directory.Delete(entry, recursive: (attributes & FileAttributes.ReparsePoint) == 0); + } + else + { + File.Delete(entry); + } + } + } + + private static bool EndsWithDirectorySequence(string path, string suffix) + { + var start = path.Length - suffix.Length; + return start >= 0 + && (start == 0 || path[start - 1] == Path.DirectorySeparatorChar) + && path.EndsWith(suffix, StringComparison.OrdinalIgnoreCase); + } + + private static bool IsSameOrAncestor(string candidate, string path) + { + return string.Equals(candidate, path, StringComparison.OrdinalIgnoreCase) + || path.StartsWith(candidate + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase); + } + + private static bool PathContainsSymbolicLink(string path) + { + var root = Path.GetPathRoot(path); + if (string.IsNullOrEmpty(root)) + { + return false; + } + + var current = root; + foreach (var segment in path[root.Length..].Split(Path.DirectorySeparatorChar, + StringSplitOptions.RemoveEmptyEntries)) + { + current = Path.Combine(current, segment); + if (Directory.Exists(current) + && (new DirectoryInfo(current).Attributes & FileAttributes.ReparsePoint) != 0) + { + return true; + } + } + + return false; + } + private static Dictionary ReadExtensionProjects(string repositoryRoot) { var solutionPath = Path.Combine(repositoryRoot, "BootstrapBlazor.Extensions.slnx"); diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/README.md b/tools/BootstrapBlazor.LLMsDocsGenerator/README.md index 2f35fb45..50820a74 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: @@ -117,23 +119,23 @@ Once installed, the tool is invoked with the command name `llms-docs`. ## Usage -Both path 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`, specify a dedicated `--output` directory: its existing contents will be deleted. 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 layout stays `/wwwroot/llms/llms.txt` and `components/*.txt`, with relative index links suitable for copying into a package. Existing generated extension `.txt` files are removed on regeneration; unmarked files are preserved, so use a dedicated output directory for packaging. +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. Before writing, the tool creates the output directory if needed or **deletes all its existing contents**, including unmarked files and subdirectories. Working directories, repository roots, source directories outside the skill references directory, and paths through symbolic links are rejected. 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. @@ -175,13 +177,13 @@ dotnet run --project "..\BootstrapBlazor.Extensions\tools\BootstrapBlazor.LLMsDo ### BootstrapBlazor NuGet packaging -From the `BootstrapBlazor` repository root, generate core-only documentation into a dedicated staging directory: +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 "artifacts\llms-pack" +dotnet llms-docs --core-only --root "src\BootstrapBlazor.Server" --output "src\BootstrapBlazor\skills\bootstrapblazor\references" ``` -Copy the contents of `artifacts\llms-pack\wwwroot\llms` into `src\BootstrapBlazor\skills\bootstrapblazor\references` for packaging. 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. +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 diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md b/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md index cffe2371..2917a821 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 进行了优化: @@ -117,23 +119,23 @@ 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` 获取,因此该文件仍为必需。不生成扩展文档、扩展索引章节或链接;扩展也提供的服务仍保留核心服务文档。输出布局仍为 `/wwwroot/llms/llms.txt` 与 `components/*.txt`,索引使用相对链接,可直接复制到包内。重新生成时会清理已有的带生成标记的扩展 `.txt`,保留无标记文件,因此打包请使用独立输出目录。 +使用 `--core-only` 时,无需修改 `docs.json`,生成器会忽略 `extensions` 节;无需扩展仓库或解决方案,即使存在也不会读取。核心分类与内置服务仍从 `docs.json` 获取,因此该文件仍为必需。不生成扩展文档、扩展索引章节或链接;扩展也提供的服务仍保留核心服务文档。输出为 `/llms.txt` 与 `/components/*.txt`,索引使用适合包内引用的相对链接。生成前会创建不存在的输出目录,或**删除其中全部已有内容**,包括无标记文件和子目录。工作目录、仓库根目录、skill references 以外的源码目录,以及经过符号链接的路径会被拒绝。 源码工程 `.csproj` 中显式声明的 ``(包括别名和静态导入)会应用到该工程的 C# 文件,不会在合并分析时泄漏到其他工程。 @@ -175,13 +177,13 @@ dotnet run --project "..\BootstrapBlazor.Extensions\tools\BootstrapBlazor.LLMsDo ### BootstrapBlazor NuGet 打包 -在 `BootstrapBlazor` 仓库根目录,将核心文档生成到独立的暂存目录: +在 `BootstrapBlazor` 仓库根目录,将核心文档直接生成到 skill 的 references 目录: ```powershell -dotnet llms-docs --core-only --root "src\BootstrapBlazor.Server" --output "artifacts\llms-pack" +dotnet llms-docs --core-only --root "src\BootstrapBlazor.Server" --output "src\BootstrapBlazor\skills\bootstrapblazor\references" ``` -将 `artifacts\llms-pack\wwwroot\llms` 的内容复制到 `src\BootstrapBlazor\skills\bootstrapblazor\references` 随包分发,无需再使用移除扩展配置的暂存 `docs.json`。BootstrapBlazor.Server 发布时不要传 `--core-only`,以保持完整官网索引、核心与扩展文档;原有发布命令及输出路径不变。 +无需再使用移除扩展配置的暂存 `docs.json`。BootstrapBlazor.Server 发布时不要传 `--core-only`,以保持完整官网索引、核心与扩展文档;原有发布命令及输出路径不变。 ## CI/CD 集成 From 1fcc4bdac6888327f3f86aee449d958726a69e50 Mon Sep 17 00:00:00 2001 From: Argo Zhang Date: Sat, 14 Nov 2026 17:02:51 +0800 Subject: [PATCH 4/4] fix(LLMsDocsGenerator): preserve core-only output contents Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../ArgumentsHelper.cs | 2 +- .../DocsGenerator.cs | 87 +------------------ .../README.md | 4 +- .../README.zh-CN.md | 4 +- 4 files changed, 6 insertions(+), 91 deletions(-) diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs b/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs index 503e54bf..80272669 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs @@ -19,7 +19,7 @@ public static ParseResult Parse(string[] args) }; var outputFolderOption = new Option("--output") { - Description = "Set the output folder (core-only clears it; default writes to wwwroot/llms)", + Description = "Set the output folder (core-only writes directly; default writes to wwwroot/llms)", DefaultValueFactory = _ => defaultFolder }; var coreOnlyOption = new Option("--core-only") diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs b/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs index 662686de..f7c9d4bb 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs @@ -96,14 +96,7 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder // Chinese documentation only: the index at the docs root and one file per // component (Chinese text extracted from the bilingual blocks) under // the components/ directory. - if (coreOnly) - { - PrepareCoreOnlyOutput(_outputPath, _sourcePath, rootFolder); - } - else - { - Directory.CreateDirectory(_outputPath); - } + Directory.CreateDirectory(_outputPath); var indexPath = Path.Combine(_outputPath, "llms.txt"); await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh")); Logger($"Generated: {indexPath}"); @@ -144,84 +137,6 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder Logger("Documentation generation complete!"); } - private static void PrepareCoreOnlyOutput(string outputPath, string sourcePath, string rootFolder) - { - var fullOutputPath = Path.TrimEndingDirectorySeparator(Path.GetFullPath(outputPath)); - var expectedSuffix = Path.Combine("skills", "bootstrapblazor", "references"); - if (!EndsWithDirectorySequence(fullOutputPath, expectedSuffix) - || PathContainsSymbolicLink(fullOutputPath)) - { - throw new ArgumentException( - $"Core-only output must be a BootstrapBlazor skill references directory without symbolic links: {fullOutputPath}", - nameof(outputPath)); - } - - var protectedPaths = new[] - { - Directory.GetCurrentDirectory(), - Path.GetFullPath(sourcePath), - Path.GetFullPath(rootFolder) - }; - if (protectedPaths.Any(path => - IsSameOrAncestor(fullOutputPath, Path.TrimEndingDirectorySeparator(Path.GetFullPath(path))))) - { - throw new ArgumentException( - $"Core-only output must not be a working or source directory: {fullOutputPath}", - nameof(outputPath)); - } - - Directory.CreateDirectory(fullOutputPath); - foreach (var entry in Directory.EnumerateFileSystemEntries(fullOutputPath)) - { - var attributes = File.GetAttributes(entry); - if ((attributes & FileAttributes.Directory) != 0) - { - Directory.Delete(entry, recursive: (attributes & FileAttributes.ReparsePoint) == 0); - } - else - { - File.Delete(entry); - } - } - } - - private static bool EndsWithDirectorySequence(string path, string suffix) - { - var start = path.Length - suffix.Length; - return start >= 0 - && (start == 0 || path[start - 1] == Path.DirectorySeparatorChar) - && path.EndsWith(suffix, StringComparison.OrdinalIgnoreCase); - } - - private static bool IsSameOrAncestor(string candidate, string path) - { - return string.Equals(candidate, path, StringComparison.OrdinalIgnoreCase) - || path.StartsWith(candidate + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase); - } - - private static bool PathContainsSymbolicLink(string path) - { - var root = Path.GetPathRoot(path); - if (string.IsNullOrEmpty(root)) - { - return false; - } - - var current = root; - foreach (var segment in path[root.Length..].Split(Path.DirectorySeparatorChar, - StringSplitOptions.RemoveEmptyEntries)) - { - current = Path.Combine(current, segment); - if (Directory.Exists(current) - && (new DirectoryInfo(current).Attributes & FileAttributes.ReparsePoint) != 0) - { - return true; - } - } - - return false; - } - private static Dictionary ReadExtensionProjects(string repositoryRoot) { var solutionPath = Path.Combine(repositoryRoot, "BootstrapBlazor.Extensions.slnx"); diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/README.md b/tools/BootstrapBlazor.LLMsDocsGenerator/README.md index 50820a74..175f32ca 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/README.md +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/README.md @@ -119,7 +119,7 @@ Once installed, the tool is invoked with the command name `llms-docs`. ## Usage -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`, specify a dedicated `--output` directory: its existing contents will be deleted. 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. @@ -135,7 +135,7 @@ Only source projects listed in `BootstrapBlazor.Extensions.slnx` are scanned. Pa 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. Before writing, the tool creates the output directory if needed or **deletes all its existing contents**, including unmarked files and subdirectories. Working directories, repository roots, source directories outside the skill references directory, and paths through symbolic links are rejected. +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. diff --git a/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md b/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md index 2917a821..e2c3b6d5 100644 --- a/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md +++ b/tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md @@ -119,7 +119,7 @@ dotnet tool uninstall --global BootstrapBlazor.LLMsDocsGenerator ## 使用方法 -两个路径参数各自默认为当前工作目录(`.`)。在 BB 的 `src/BootstrapBlazor.Server` 目录直接执行 `llms-docs` 即可将文档生成到该工程。使用 `--core-only` 时,需指定专用的 `--output` 目录:其已有内容会被删除。覆盖 `--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)`(路径不含空格时)。 @@ -135,7 +135,7 @@ dotnet tool uninstall --global BootstrapBlazor.LLMsDocsGenerator 配置了扩展包但缺少同级扩展源码仓库时,生成会失败且不改动已有文档。配置中的组件或服务类型无法解析时,也会在写入文件、清理过期文档之前报错。多个包共用的服务接口仍使用一份文档,按配置的包分别列出注册方法,使用时选择对应包的注册方式。 -使用 `--core-only` 时,无需修改 `docs.json`,生成器会忽略 `extensions` 节;无需扩展仓库或解决方案,即使存在也不会读取。核心分类与内置服务仍从 `docs.json` 获取,因此该文件仍为必需。不生成扩展文档、扩展索引章节或链接;扩展也提供的服务仍保留核心服务文档。输出为 `/llms.txt` 与 `/components/*.txt`,索引使用适合包内引用的相对链接。生成前会创建不存在的输出目录,或**删除其中全部已有内容**,包括无标记文件和子目录。工作目录、仓库根目录、skill references 以外的源码目录,以及经过符号链接的路径会被拒绝。 +使用 `--core-only` 时,无需修改 `docs.json`,生成器会忽略 `extensions` 节;无需扩展仓库或解决方案,即使存在也不会读取。核心分类与内置服务仍从 `docs.json` 获取,因此该文件仍为必需。不生成扩展文档、扩展索引章节或链接;扩展也提供的服务仍保留核心服务文档。输出为 `/llms.txt` 与 `/components/*.txt`,索引使用适合包内引用的相对链接。不存在的输出目录会自动创建,不会清空已有内容;仅删除带生成器标记的过期文件,无标记文件与子目录会保留。 源码工程 `.csproj` 中显式声明的 ``(包括别名和静态导入)会应用到该工程的 C# 文件,不会在合并分析时泄漏到其他工程。