Remove Uri sources from navigation rendering. (#1546)

* Remove Uri sources from navigation rendering.

This PR removes the need to keep track of NavigationSource on markdown files to render the navigation.

Previous to this we needed the keep this around to track the 'real' parent of a section once it may have been reshuffled by `navigation.yml`.

We now more diligently build the global navigation more truthfully and can relay on walking the current navigation items `.Parent` to find the proper root to render.

This includes scrubbing/skipping phantoms from the navigation.

Another step to refactoring our navigation acyclic graph as the single source of truth.

* remove temporary pragma's while refactoring

* use logger not Console.WriteLine

Author: Mpdreamz

src/Elastic.ApiExplorer/OpenApiGenerator.cs

@@ -288,7 +288,7 @@ private async Task<IFileInfo> Render<T>(INavigationItem current, T page, ApiRend
 		if (!outputFile.Directory!.Exists)
 			outputFile.Directory.Create();
 
-		var navigationRenderResult = await navigationRenderer.RenderNavigation(current.NavigationRoot, new Uri("http://ignored.example"), INavigationHtmlWriter.AllLevels, ctx);
+		var navigationRenderResult = await navigationRenderer.RenderNavigation(current.NavigationRoot, INavigationHtmlWriter.AllLevels, ctx);
 		renderContext = renderContext with
 		{
 			CurrentNavigation = current,

src/Elastic.Documentation.Site/Navigation/INavigationHtmlWriter.cs

@@ -10,8 +10,7 @@ public interface INavigationHtmlWriter
 {
 	const int AllLevels = -1;
 
-	Task<NavigationRenderResult> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource,
-		int maxLevel, Cancel ctx = default);
+	Task<NavigationRenderResult> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, int maxLevel, Cancel ctx = default);
 
 	async Task<string> Render(NavigationViewModel model, Cancel ctx)
 	{

src/Elastic.Documentation.Site/Navigation/IsolatedBuildNavigationHtmlWriter.cs

@@ -13,8 +13,9 @@ public class IsolatedBuildNavigationHtmlWriter(BuildContext context, IRootNaviga
 {
 	private readonly ConcurrentDictionary<(string, int), string> _renderedNavigationCache = [];
 
-	public async Task<NavigationRenderResult> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation,
-		Uri navigationSource, int maxLevel, Cancel ctx = default)
+	public async Task<NavigationRenderResult> RenderNavigation(
+		IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, int maxLevel, Cancel ctx = default
+	)
 	{
 		var navigation = context.Configuration.Features.PrimaryNavEnabled || currentRootNavigation.IsUsingNavigationDropdown
 			? currentRootNavigation

src/Elastic.Markdown/HtmlWriter.cs

@@ -56,8 +56,8 @@ private async Task<RenderResult> RenderLayout(MarkdownFile markdown, MarkdownDoc
 		var html = MarkdownFile.CreateHtml(document);
 		await DocumentationSet.Tree.Resolve(ctx);
 
-		var fullNavigationRenderResult = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, INavigationHtmlWriter.AllLevels, ctx);
-		var miniNavigationRenderResult = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, 1, ctx);
+		var fullNavigationRenderResult = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, INavigationHtmlWriter.AllLevels, ctx);
+		var miniNavigationRenderResult = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, 1, ctx);
 
 		var navigationHtmlRenderResult = DocumentationSet.Context.Configuration.Features.LazyLoadNavigation
 			? miniNavigationRenderResult

src/Elastic.Markdown/IO/MarkdownFile.cs

@@ -57,7 +57,6 @@ DocumentationSet set
 		ScopeDirectory = build.Configuration.ScopeDirectory;
 
 		NavigationRoot = set.Tree;
-		NavigationSource = set.Source;
 	}
 
 	public bool PartOfNavigation { get; set; }
@@ -66,8 +65,6 @@ DocumentationSet set
 
 	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; set; }
 
-	public Uri NavigationSource { get; set; }
-
 	private IDiagnosticsCollector Collector { get; }
 
 	public string? UrlPathPrefix { get; }

src/Elastic.Markdown/IO/Navigation/DocumentationGroup.cs

@@ -11,7 +11,7 @@
 
 namespace Elastic.Markdown.IO.Navigation;
 
-[DebuggerDisplay("Group >{Depth} {FolderName} ({NavigationItems.Count} items)")]
+[DebuggerDisplay("Toc: {Depth} {NavigationSource} > ({NavigationItems.Count} items)")]
 public class DocumentationGroup : INodeNavigationItem<MarkdownFile, INavigationItem>
 {
 	private readonly TableOfContentsTreeCollector _treeCollector;
@@ -138,7 +138,6 @@ void AddToNavigationItems(INavigationItem item, ref int fileIndex)
 				// TODO these have to be refactor to be pure navigational properties
 				md.ScopeDirectory = file.TableOfContentsScope.ScopeDirectory;
 				md.NavigationRoot = rootNavigationItem;
-				md.NavigationSource = NavigationSource;
 
 				foreach (var extension in lookups.EnabledExtensions)
 					extension.Visit(d, tocItem);

src/Elastic.Markdown/IO/Navigation/TableOfContentsTree.cs

@@ -8,7 +8,7 @@
 
 namespace Elastic.Markdown.IO.Navigation;
 
-[DebuggerDisplay("Toc >{Depth} {FolderName} ({NavigationItems.Count} items)")]
+[DebuggerDisplay("Toc: {Depth} {NavigationSource} > ({NavigationItems.Count} items)")]
 public class TableOfContentsTree : DocumentationGroup, IRootNavigationItem<MarkdownFile, INavigationItem>
 {
 	public Uri Source { get; }

src/Elastic.Markdown/IO/Navigation/TableOfContentsTreeCollector.cs

@@ -11,11 +11,7 @@ public class TableOfContentsTreeCollector
 {
 	private Dictionary<Uri, TableOfContentsTree> NestedTableOfContentsTrees { get; } = [];
 
-	public void Collect(Uri source, TableOfContentsTree tree) =>
-		NestedTableOfContentsTrees[source] = tree;
-
-	public void Collect(TocReference tocReference, TableOfContentsTree tree) =>
-		NestedTableOfContentsTrees[tocReference.Source] = tree;
+	public void Collect(Uri source, TableOfContentsTree tree) => NestedTableOfContentsTrees[source] = tree;
 
 	public bool TryGetTableOfContentsTree(Uri source, [NotNullWhen(true)] out TableOfContentsTree? tree) =>
 		NestedTableOfContentsTrees.TryGetValue(source, out tree);

src/tooling/docs-assembler/AssembleSources.cs

@@ -20,7 +20,8 @@
 using YamlDotNet.RepresentationModel;
 
 namespace Documentation.Assembler;
-public record TocTopLevelMapping
+
+public record NavigationTocMapping
 {
 	public required Uri Source { get; init; }
 	public required string SourcePathPrefix { get; init; }
@@ -30,7 +31,7 @@ public record TocTopLevelMapping
 
 public record TocConfigurationMapping
 {
-	public required TocTopLevelMapping TopLevel { get; init; }
+	public required NavigationTocMapping TopLevel { get; init; }
 	public required ConfigurationFile RepositoryConfigurationFile { get; init; }
 	public required TableOfContentsConfiguration TableOfContentsConfiguration { get; init; }
 }
@@ -40,7 +41,7 @@ public class AssembleSources
 	public AssembleContext AssembleContext { get; }
 	public FrozenDictionary<string, AssemblerDocumentationSet> AssembleSets { get; }
 
-	public FrozenDictionary<Uri, TocTopLevelMapping> TocTopLevelMappings { get; }
+	public FrozenDictionary<Uri, NavigationTocMapping> NavigationTocMappings { get; }
 
 	public FrozenDictionary<string, IReadOnlyCollection<string>> HistoryMappings { get; }
 
@@ -61,19 +62,19 @@ public static async Task<AssembleSources> AssembleAsync(ILoggerFactory logger, A
 	private AssembleSources(ILoggerFactory logger, AssembleContext assembleContext, Checkout[] checkouts, VersionsConfiguration versionsConfiguration)
 	{
 		AssembleContext = assembleContext;
-		TocTopLevelMappings = GetConfiguredSources(assembleContext);
+		NavigationTocMappings = GetTocMappings(assembleContext);
 		HistoryMappings = GetHistoryMapping(assembleContext);
 		var linkIndexProvider = Aws3LinkIndexReader.CreateAnonymous();
 		var crossLinkFetcher = new AssemblerCrossLinkFetcher(logger, assembleContext.Configuration, assembleContext.Environment, linkIndexProvider);
-		UriResolver = new PublishEnvironmentUriResolver(TocTopLevelMappings, assembleContext.Environment);
+		UriResolver = new PublishEnvironmentUriResolver(NavigationTocMappings, assembleContext.Environment);
 		var crossLinkResolver = new CrossLinkResolver(crossLinkFetcher, UriResolver);
 		AssembleSets = checkouts
 			.Where(c => c.Repository is { Skip: false })
 			.Select(c => new AssemblerDocumentationSet(logger, assembleContext, c, crossLinkResolver, TreeCollector, versionsConfiguration))
 			.ToDictionary(s => s.Checkout.Repository.Name, s => s)
 			.ToFrozenDictionary();
 
-		TocConfigurationMapping = TocTopLevelMappings
+		TocConfigurationMapping = NavigationTocMappings
 			.Select(kv =>
 			{
 				var repo = kv.Value.Source.Scheme;
@@ -148,11 +149,11 @@ static void ReadHistoryMappings(IDictionary<string, IReadOnlyCollection<string>>
 	}
 
 
-	public static FrozenDictionary<Uri, TocTopLevelMapping> GetConfiguredSources(AssembleContext context)
+	public static FrozenDictionary<Uri, NavigationTocMapping> GetTocMappings(AssembleContext context)
 	{
-		var dictionary = new Dictionary<Uri, TocTopLevelMapping>();
+		var dictionary = new Dictionary<Uri, NavigationTocMapping>();
 		var reader = new YamlStreamReader(context.NavigationPath, context.Collector);
-		var entries = new List<KeyValuePair<Uri, TocTopLevelMapping>>();
+		var entries = new List<KeyValuePair<Uri, NavigationTocMapping>>();
 		foreach (var entry in reader.Read())
 		{
 			switch (entry.Key)
@@ -167,7 +168,7 @@ public static FrozenDictionary<Uri, TocTopLevelMapping> GetConfiguredSources(Ass
 		return dictionary.ToFrozenDictionary();
 
 		static void ReadTocBlocks(
-			List<KeyValuePair<Uri, TocTopLevelMapping>> entries,
+			List<KeyValuePair<Uri, NavigationTocMapping>> entries,
 			YamlStreamReader reader,
 			KeyValuePair<YamlNode, YamlNode> entry,
 			string? parent,
@@ -196,7 +197,7 @@ static void ReadTocBlocks(
 			}
 		}
 		static void ReadBlock(
-			List<KeyValuePair<Uri, TocTopLevelMapping>> entries,
+			List<KeyValuePair<Uri, NavigationTocMapping>> entries,
 			YamlStreamReader reader,
 			YamlMappingNode tocEntry,
 			string? parent,
@@ -259,14 +260,14 @@ static void ReadBlock(
 			topLevelSource ??= sourceUri;
 			parentSource ??= sourceUri;
 
-			var tocTopLevelMapping = new TocTopLevelMapping
+			var tocTopLevelMapping = new NavigationTocMapping
 			{
 				Source = sourceUri,
 				SourcePathPrefix = pathPrefix,
 				TopLevelSource = topLevelSource,
 				ParentSource = parentSource
 			};
-			entries.Add(new KeyValuePair<Uri, TocTopLevelMapping>(sourceUri, tocTopLevelMapping));
+			entries.Add(new KeyValuePair<Uri, NavigationTocMapping>(sourceUri, tocTopLevelMapping));
 
 			foreach (var entry in tocEntry.Children)
 			{

src/tooling/docs-assembler/Building/PublishEnvironmentUriResolver.cs

@@ -11,14 +11,14 @@ namespace Documentation.Assembler.Building;
 
 public class PublishEnvironmentUriResolver : IUriEnvironmentResolver
 {
-	private readonly FrozenDictionary<Uri, TocTopLevelMapping> _topLevelMappings;
+	private readonly FrozenDictionary<Uri, NavigationTocMapping> _topLevelMappings;
 	private Uri BaseUri { get; }
 
 	private PublishEnvironment PublishEnvironment { get; }
 
 	private IReadOnlyList<string> TableOfContentsPrefixes { get; }
 
-	public PublishEnvironmentUriResolver(FrozenDictionary<Uri, TocTopLevelMapping> topLevelMappings, PublishEnvironment environment)
+	public PublishEnvironmentUriResolver(FrozenDictionary<Uri, NavigationTocMapping> topLevelMappings, PublishEnvironment environment)
 	{
 		_topLevelMappings = topLevelMappings;
 		PublishEnvironment = environment;