add path shortening as a configurable option

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<string> GetPathList(DocumentationObject documentationObject)
+    private static List<string> GetPathList(DocumentationObject documentationObject, bool pathShortening)
     {
         var pathList = new List<string>();
 
@@ -170,15 +170,23 @@ private static List<string> 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<string> 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<string> 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<string> parts)

src/Doki.Output.Markdown/MarkdownBuilder.cs

@@ -10,11 +10,15 @@ private static readonly Func<string, bool>
 
     private readonly string[] _currentPathParts;
     private readonly List<Element> _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();

src/Doki.Output.Markdown/MarkdownOutput.cs

@@ -4,7 +4,7 @@
 
 namespace Doki.Output.Markdown;
 
-public sealed class MarkdownOutput(OutputOptions<MarkdownOutput> 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<Element> 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<Element> 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)
         {

src/Doki.Output.Markdown/MarkdownOutputExtensions.cs

@@ -10,7 +10,7 @@ public static IServiceCollection AddMarkdownOutput(this IServiceCollection servi
     {
         ArgumentNullException.ThrowIfNull(services);
 
-        services.AddOutputOptions<MarkdownOutput>("Doki.Output.Markdown");
+        services.AddOutputOptions<MarkdownOutput, MarkdownOutputOptions>("Doki.Output.Markdown");
 
         services.AddSingleton<IOutput, MarkdownOutput>();
 

src/Doki.Output.Markdown/MarkdownOutputOptions.cs

@@ -0,0 +1,6 @@
+namespace Doki.Output.Markdown;
+
+public sealed record MarkdownOutputOptions : OutputOptions<MarkdownOutput>
+{
+    public bool PathShortening { get; init; } = true;
+}

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<MarkdownOutput>
+        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<MarkdownOutput>
+        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<MarkdownOutput>
+        generator.AddOutput(new MarkdownOutput(new MarkdownOutputOptions
         {
             OutputDirectory = snapshot.OutputDirectory
         }));