From 5dc086e9b476bc05056001316fb6472d8ff7a14e Mon Sep 17 00:00:00 2001 From: dvolper Date: Mon, 1 Jul 2024 20:42:28 +0200 Subject: [PATCH] add path shortening as a configurable option --- .../InternalExtensions.cs | 38 +++++++++++-------- src/Doki.Output.Markdown/MarkdownBuilder.cs | 8 +++- src/Doki.Output.Markdown/MarkdownOutput.cs | 10 ++--- .../MarkdownOutputExtensions.cs | 2 +- .../MarkdownOutputOptions.cs | 6 +++ tests/Doki.Tests.Snapshots/SnapshotTests.cs | 6 +-- 6 files changed, 44 insertions(+), 26 deletions(-) create mode 100644 src/Doki.Output.Markdown/MarkdownOutputOptions.cs diff --git a/src/Doki.Output.Markdown/InternalExtensions.cs b/src/Doki.Output.Markdown/InternalExtensions.cs index 447c06b..bb56129 100644 --- a/src/Doki.Output.Markdown/InternalExtensions.cs +++ b/src/Doki.Output.Markdown/InternalExtensions.cs @@ -73,10 +73,10 @@ public static Text BuildText(this MarkdownBuilder builder, DocumentationObject o return text; } - public static string BuildRelativePath(this MarkdownBuilder builder, DocumentationObject to, + public static string BuildRelativePath(this MarkdownBuilder builder, DocumentationObject to, bool pathShortening, params string[] additionalParts) { - return builder.BuildRelativePath(to.GetPath(), additionalParts); + return builder.BuildRelativePath(to.GetPath(pathShortening), additionalParts); } public static Element BuildLinkTo(this MarkdownBuilder builder, DocumentationObject to, string? text = null) @@ -100,7 +100,7 @@ public static Element BuildLinkTo(this MarkdownBuilder builder, DocumentationObj } else { - relativePath = builder.BuildRelativePath(to, "README.md"); + relativePath = builder.BuildRelativePath(to, builder.Options.PathShortening, "README.md"); } break; @@ -111,7 +111,7 @@ public static Element BuildLinkTo(this MarkdownBuilder builder, DocumentationObj asText = !memberDocumentation.IsDocumented; - relativePath = builder.BuildRelativePath(memberDocumentation) + ".md"; + relativePath = builder.BuildRelativePath(memberDocumentation, builder.Options.PathShortening) + ".md"; break; } default: @@ -120,8 +120,8 @@ public static Element BuildLinkTo(this MarkdownBuilder builder, DocumentationObj or DocumentationContentType.Namespace; relativePath = indexFile - ? builder.BuildRelativePath(to, "README.md") - : builder.BuildRelativePath(to) + ".md"; + ? builder.BuildRelativePath(to, builder.Options.PathShortening, "README.md") + : builder.BuildRelativePath(to, builder.Options.PathShortening) + ".md"; break; } } @@ -156,7 +156,7 @@ private static string GetPathId(this DocumentationObject documentationObject) return documentationObject.Id.Replace('`', '_'); } - private static List GetPathList(DocumentationObject documentationObject) + private static List GetPathList(DocumentationObject documentationObject, bool pathShortening) { var pathList = new List(); @@ -170,15 +170,23 @@ private static List GetPathList(DocumentationObject documentationObject) if (typeDocumentationReference.Namespace != null) { - if (typeDocumentationReference.Assembly != null && - typeDocumentationReference.Namespace.StartsWith(typeDocumentationReference.Assembly + ".")) - pathList.Add( - typeDocumentationReference.Namespace[(typeDocumentationReference.Assembly.Length + 1)..]); + if (pathShortening && typeDocumentationReference.Assembly != null) + { + if (typeDocumentationReference.Namespace == typeDocumentationReference.Assembly) + pathList.Add("_"); + else if (typeDocumentationReference.Namespace.StartsWith(typeDocumentationReference.Assembly + + ".")) + pathList.Add( + typeDocumentationReference.Namespace + [(typeDocumentationReference.Assembly.Length + 1)..]); + else pathList.Add(typeDocumentationReference.Namespace); + } else pathList.Add(typeDocumentationReference.Namespace); } var pathId = typeDocumentationReference.GetPathId(); - if (typeDocumentationReference.Namespace != null && + if (pathShortening && + typeDocumentationReference.Namespace != null && pathId.StartsWith(typeDocumentationReference.Namespace + ".")) pathList.Add(pathId[(typeDocumentationReference.Namespace.Length + 1)..]); else pathList.Add(pathId); @@ -187,7 +195,7 @@ private static List GetPathList(DocumentationObject documentationObject) } case MemberDocumentation { Parent: not null } memberDocumentation: { - var parentPathList = GetPathList(memberDocumentation.Parent); + var parentPathList = GetPathList(memberDocumentation.Parent, pathShortening); //TODO path shortening (see TypeDocumentationReference) parentPathList.Add(memberDocumentation.GetPathId()); @@ -208,9 +216,9 @@ private static List GetPathList(DocumentationObject documentationObject) return pathList; } - public static string GetPath(this DocumentationObject documentationObject) + public static string GetPath(this DocumentationObject documentationObject, bool pathShortening) { - return GetPathList(documentationObject).CombineToPath(); + return GetPathList(documentationObject, pathShortening).CombineToPath(); } public static string CombineToPath(this ICollection parts) diff --git a/src/Doki.Output.Markdown/MarkdownBuilder.cs b/src/Doki.Output.Markdown/MarkdownBuilder.cs index b378008..5ad66a5 100644 --- a/src/Doki.Output.Markdown/MarkdownBuilder.cs +++ b/src/Doki.Output.Markdown/MarkdownBuilder.cs @@ -10,11 +10,15 @@ private static readonly Func private readonly string[] _currentPathParts; private readonly List _elements = []; + + public MarkdownOutputOptions Options { get; } - public MarkdownBuilder(string currentPath) + public MarkdownBuilder(string currentPath, MarkdownOutputOptions options) { var currentPathParts = currentPath.Split('/'); _currentPathParts = currentPathParts.Where(PathPartFilter).ToArray(); + + Options = options; } public MarkdownBuilder Add(Element element) @@ -45,7 +49,7 @@ public string BuildRelativePath(string to, params string[] additionalParts) } relativePathParts.AddRange(path.Skip(commonPathParts)); - + relativePathParts.AddRange(additionalParts); return relativePathParts.CombineToPath(); diff --git a/src/Doki.Output.Markdown/MarkdownOutput.cs b/src/Doki.Output.Markdown/MarkdownOutput.cs index 3eb43b3..d253c1e 100644 --- a/src/Doki.Output.Markdown/MarkdownOutput.cs +++ b/src/Doki.Output.Markdown/MarkdownOutput.cs @@ -4,7 +4,7 @@ namespace Doki.Output.Markdown; -public sealed class MarkdownOutput(OutputOptions options) : IOutput +public sealed class MarkdownOutput(MarkdownOutputOptions options) : IOutput { public Task BeginAsync(CancellationToken cancellationToken = default) { @@ -72,14 +72,14 @@ public async Task WriteAsync(TypeDocumentation typeDocumentation, CancellationTo { ArgumentNullException.ThrowIfNull(typeDocumentation); - var currentPath = typeDocumentation.GetPath(); + var currentPath = typeDocumentation.GetPath(options.PathShortening); var typeDocumentationFile = new FileInfo(Path.Combine(options.OutputDirectory.FullName, currentPath, "README.md")); if (!typeDocumentationFile.Directory!.Exists) typeDocumentationFile.Directory.Create(); - var markdown = new MarkdownBuilder(currentPath); + var markdown = new MarkdownBuilder(currentPath, options); markdown.Add(markdown.BuildBreadcrumbs(typeDocumentation)) .Add(new Heading(typeDocumentation.Name, 1).Append($" {Enum.GetName(typeDocumentation.ContentType)}")) .Add(new Heading(nameof(TypeDocumentation.Definition), 2)); @@ -201,7 +201,7 @@ private static IEnumerable BuildInheritanceChain(MarkdownBuilder markdo private (FileInfo, MarkdownBuilder) Prepare(DocumentationObject documentationObject, string name, string? description = null) { - var currentPath = documentationObject.GetPath(); + var currentPath = documentationObject.GetPath(options.PathShortening); var file = new FileInfo(Path.Combine(options.OutputDirectory.FullName, currentPath, "README.md")); @@ -210,7 +210,7 @@ private static IEnumerable BuildInheritanceChain(MarkdownBuilder markdo var heading = new Heading(name, 1); if (documentationObject.ContentType == DocumentationContentType.Namespace) heading.Append(" Namespace"); - var markdown = new MarkdownBuilder(currentPath).Add(heading); + var markdown = new MarkdownBuilder(currentPath, options).Add(heading); if (description != null) { diff --git a/src/Doki.Output.Markdown/MarkdownOutputExtensions.cs b/src/Doki.Output.Markdown/MarkdownOutputExtensions.cs index 0268e40..89379a8 100644 --- a/src/Doki.Output.Markdown/MarkdownOutputExtensions.cs +++ b/src/Doki.Output.Markdown/MarkdownOutputExtensions.cs @@ -10,7 +10,7 @@ public static IServiceCollection AddMarkdownOutput(this IServiceCollection servi { ArgumentNullException.ThrowIfNull(services); - services.AddOutputOptions("Doki.Output.Markdown"); + services.AddOutputOptions("Doki.Output.Markdown"); services.AddSingleton(); diff --git a/src/Doki.Output.Markdown/MarkdownOutputOptions.cs b/src/Doki.Output.Markdown/MarkdownOutputOptions.cs new file mode 100644 index 0000000..d7178c9 --- /dev/null +++ b/src/Doki.Output.Markdown/MarkdownOutputOptions.cs @@ -0,0 +1,6 @@ +namespace Doki.Output.Markdown; + +public sealed record MarkdownOutputOptions : OutputOptions +{ + public bool PathShortening { get; init; } = true; +} \ No newline at end of file diff --git a/tests/Doki.Tests.Snapshots/SnapshotTests.cs b/tests/Doki.Tests.Snapshots/SnapshotTests.cs index 7345973..163fc71 100644 --- a/tests/Doki.Tests.Snapshots/SnapshotTests.cs +++ b/tests/Doki.Tests.Snapshots/SnapshotTests.cs @@ -22,7 +22,7 @@ public async Task Test_RootNamespaceIsParentNamespace() generator.AddAssembly(typeof(TestParentRootNamespaceClass).Assembly, emptyDocumentation); - generator.AddOutput(new MarkdownOutput(new OutputOptions + generator.AddOutput(new MarkdownOutput(new MarkdownOutputOptions { OutputDirectory = snapshot.OutputDirectory })); @@ -48,7 +48,7 @@ public async Task Test_InheritanceChain() generator.AddAssembly(typeof(AbstractClass).Assembly, emptyDocumentation); generator.AddAssembly(typeof(SimpleClass).Assembly, emptyDocumentation); - generator.AddOutput(new MarkdownOutput(new OutputOptions + generator.AddOutput(new MarkdownOutput(new MarkdownOutputOptions { OutputDirectory = snapshot.OutputDirectory })); @@ -102,7 +102,7 @@ public async Task Test_Assembly() generator.AddAssembly(typeof(ClassWithCRefs).Assembly, emptyDocumentation); - generator.AddOutput(new MarkdownOutput(new OutputOptions + generator.AddOutput(new MarkdownOutput(new MarkdownOutputOptions { OutputDirectory = snapshot.OutputDirectory }));