From 8e594aa0b044cbfcaa9c597f7252069e8ce98a20 Mon Sep 17 00:00:00 2001 From: Laszlo Paillat Date: Fri, 18 Oct 2024 23:35:40 +0200 Subject: [PATCH] added ExcludeGenerator to exclude DocItem from the documentation generation based on regex (closes #160) --- README.md | 13 +++++- documentation/NEXT_RELEASENOTES.txt | 1 + .../DefaultDocumentation.Common/Generator.cs | 2 +- .../Internal/GeneralContext.cs | 4 -- .../DocItemGenerators/ExcludeGenerator.cs | 45 +++++++++++++++++++ 5 files changed, 59 insertions(+), 6 deletions(-) create mode 100644 source/DefaultDocumentation.Markdown/DocItemGenerators/ExcludeGenerator.cs diff --git a/README.md b/README.md index 28c66160..a1763d9c 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,7 @@ dotnet tool - [HandleLineBreak](#MarkdownConfiguration_HandleLineBreak) - [TableOfContentsModes](#MarkdownConfiguration_TableOfContentsModes) - [Url format](#MarkdownConfiguration_UrlFormat) + - [Exclude](#MarkdownConfiguration_Exclude) - [Samples](#Samples) - [Dependencies](#Dependencies) @@ -329,8 +330,9 @@ The list of plugin files to load to create the documentation. See [Plugins](#Ove `Name` or `Type Assembly` of the `IDocItemGenerator` implementations to use to generate the `DocItem` of the documentation. The default implementations provided are: +- `Exclude` or `DefaultDocumentation.Markdown.DocItemGenerators.ExcludeGenerator DefaultDocumentation.Markdown` remove `DocItem` from the documentation generation based on [MarkdownConfiguration.Exclude](#MarkdownConfiguration_Exclude). - `Overloads` or `DefaultDocumentation.Markdown.DocItemGenerators.OverloadsGenerator DefaultDocumentation.Markdown` adds pages to group constructor and method overloads the same way microsoft documentation do it. -The default value is `Overloads`. +The default value is `Exclude|Overloads`. ## UrlFactories @@ -563,6 +565,15 @@ Three arguments will be passed to the format: The default value is `[{0}]({1} '{2}')`. + +## Exclude +- configuration file: `"Markdown.Exclude": [ "", ... ]` + +Contains a collection of regex used by the `DefaultDocumentation.Markdown.DocItemGenerators.ExcludeGenerator DefaultDocumentation.Markdown` [DocItemGenerator](#Configuration_DocItemGenerators), +any `DocItem` whose id will match one of them will be excluded from the documentation generation. + +The default value is `null`. + # Samples - [DefaultDocumentation api](https://github.com/Doraku/DefaultDocumentation/blob/master/documentation/api/index.md) diff --git a/documentation/NEXT_RELEASENOTES.txt b/documentation/NEXT_RELEASENOTES.txt index 70848845..434685c5 100644 --- a/documentation/NEXT_RELEASENOTES.txt +++ b/documentation/NEXT_RELEASENOTES.txt @@ -9,6 +9,7 @@ - it is now possible to change the format of url link procuded in the markdown via Markdown.UrlFormat configuration (closes #107) - added IDocItemGenerator to customize pages generated - added OverloadsGenerator to put constructor and method overloads in the same page (closes #139) +- added ExcludeGenerator to exclude DocItem from the documentation generation based on regex (closes #160) ## Bug fixes diff --git a/source/DefaultDocumentation.Common/Generator.cs b/source/DefaultDocumentation.Common/Generator.cs index fef24803..1623d0e2 100644 --- a/source/DefaultDocumentation.Common/Generator.cs +++ b/source/DefaultDocumentation.Common/Generator.cs @@ -60,7 +60,7 @@ private Generator(Target loggerTarget, IRawSettings settings) AddSetting(settings => settings.ExternLinksFilePaths, value => !(value ?? []).Any(), value => value.ToArray()); // context settings AddSetting(settings => settings.Plugins, value => !(value ?? []).Any(), value => value.ToArray()); - AddSetting(settings => settings.DocItemGenerators, value => !(value ?? []).Any(), ["Overloads"]); + AddSetting(settings => settings.DocItemGenerators, value => !(value ?? []).Any(), ["Exclude", "Overloads"]); AddSetting(settings => settings.FileNameFactory, string.IsNullOrEmpty, "FullName"); AddSetting(settings => settings.UrlFactories, value => !(value ?? []).Any(), value => value.ToArray(), ["DocItem", "DotnetApi"]); AddSetting(settings => settings.Sections, value => !(value ?? []).Any(), value => value.ToArray(), ["Header", "Default"]); diff --git a/source/DefaultDocumentation.Common/Internal/GeneralContext.cs b/source/DefaultDocumentation.Common/Internal/GeneralContext.cs index 114dd417..4bbaa266 100644 --- a/source/DefaultDocumentation.Common/Internal/GeneralContext.cs +++ b/source/DefaultDocumentation.Common/Internal/GeneralContext.cs @@ -103,14 +103,10 @@ .. GetImplementations(availableTypes, docItemGenerator => doc #region IDocItemsContext - ISettings IDocItemsContext.Settings => Settings; - IDictionary IDocItemsContext.Items => _items; ICollection IDocItemsContext.ItemsWithOwnPage => _itemsWithOwnPage; - T? IDocItemsContext.GetSetting(string name) where T : default => GetSetting(name); - T? IDocItemsContext.GetSetting(Type? type, string name) where T : default => GetContext(type).GetSetting(name); #endregion diff --git a/source/DefaultDocumentation.Markdown/DocItemGenerators/ExcludeGenerator.cs b/source/DefaultDocumentation.Markdown/DocItemGenerators/ExcludeGenerator.cs new file mode 100644 index 00000000..718e7deb --- /dev/null +++ b/source/DefaultDocumentation.Markdown/DocItemGenerators/ExcludeGenerator.cs @@ -0,0 +1,45 @@ +using System; +using System.Linq; +using System.Text.RegularExpressions; +using DefaultDocumentation.Api; +using DefaultDocumentation.Models; + +namespace DefaultDocumentation.Markdown.DocItemGenerators; + +/// +/// Implementation of the to remove from the documentation generation based on Markdown.Exclude. +/// +public sealed class ExcludeGenerator : IDocItemGenerator +{ + /// + /// The name of this implementation used at the configuration level. + /// + public const string ConfigName = "Exclude"; + + /// + public string Name => ConfigName; + + /// + public void Generate(IDocItemsContext context) + { + context.ThrowIfNull(); + + void Remove(DocItem item) + { + context.Items.Remove(item.Id); + context.ItemsWithOwnPage.Remove(item); + + foreach (DocItem child in context.Items.Values.Where(child => child.Parent == item).ToArray()) + { + Remove(child); + } + } + + foreach (DocItem item in (context.GetSetting("Markdown.Exclude") ?? []) + .SelectMany(regex => context.Items.Values.Where(item => Regex.IsMatch(item.Id, regex))) + .ToArray()) + { + Remove(item); + } + } +}