From d8b057e2eadec796d2d5c1be41456e7f4ab5646c Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 18 Mar 2025 20:31:56 +0100 Subject: [PATCH 1/4] Restrict docset.yml configs that define toc.yml sections to ONLY link to sub toc.yml files --- docs/_docset.yml | 3 +++ .../IO/Configuration/ConfigurationFile.cs | 14 ++++++++++++-- src/Elastic.Markdown/IO/Configuration/ITocItem.cs | 2 ++ .../Configuration/TableOfContentsConfiguration.cs | 2 +- 4 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/_docset.yml b/docs/_docset.yml index 8292d5b3e..5f0cdbef8 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -1,5 +1,8 @@ project: 'doc-builder' max_toc_depth: 2 +# indicates this documentation set is not linkable by assembler. +# relaxes a few restrictions around toc building and file placement +dev_docs: true cross_links: - docs-content exclude: diff --git a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs index d6f9b79e0..855744c30 100644 --- a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs +++ b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs @@ -44,6 +44,10 @@ public record ConfigurationFile : DocumentationFile private FeatureFlags? _featureFlags; public FeatureFlags Features => _featureFlags ??= new FeatureFlags(_features); + /// This is a documentation set that is not linked to by assembler. + /// Setting this to true relaxes a few restrictions such as mixing toc references with file and folder reference + public bool DevelopmentDocs { get; } + public ConfigurationFile(BuildContext context) : base(context.ConfigurationPath, context.DocumentationSourceDirectory) { @@ -74,6 +78,9 @@ public ConfigurationFile(BuildContext context) case "max_toc_depth": MaxTocDepth = int.TryParse(reader.ReadString(entry.Entry), out var maxTocDepth) ? maxTocDepth : 1; break; + case "dev_docs": + DevelopmentDocs = bool.TryParse(reader.ReadString(entry.Entry), out var devDocs) && devDocs; + break; case "exclude": var excludes = YamlStreamReader.ReadStringArray(entry.Entry); Exclude = [.. excludes.Where(s => !string.IsNullOrEmpty(s)).Select(Glob.Parse)]; @@ -111,8 +118,11 @@ public ConfigurationFile(BuildContext context) { case "toc": var toc = new TableOfContentsConfiguration(this, _context, 0, ""); - var entries = toc.ReadChildren(reader, entry.Entry); - TableOfContents = entries; + var children = toc.ReadChildren(reader, entry.Entry); + var tocEntries = children.OfType().ToArray(); + if (!DevelopmentDocs && tocEntries.Length > 0 && children.Count != tocEntries.Length) + reader.EmitError("toc links to other toc sections it may only contain other toc references", entry.Key); + TableOfContents = children; Files = toc.Files; //side-effect ripe for refactor break; } diff --git a/src/Elastic.Markdown/IO/Configuration/ITocItem.cs b/src/Elastic.Markdown/IO/Configuration/ITocItem.cs index bd9c69c16..6d09e492d 100644 --- a/src/Elastic.Markdown/IO/Configuration/ITocItem.cs +++ b/src/Elastic.Markdown/IO/Configuration/ITocItem.cs @@ -9,3 +9,5 @@ public interface ITocItem; public record FileReference(string Path, bool Found, bool Hidden, IReadOnlyCollection Children) : ITocItem; public record FolderReference(string Path, bool Found, bool InNav, IReadOnlyCollection Children) : ITocItem; + +public record TocReference(string Path, bool Found, bool InNav, IReadOnlyCollection Children) : FolderReference(Path, Found, InNav, Children); diff --git a/src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs b/src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs index 732b95400..3aac86613 100644 --- a/src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs +++ b/src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs @@ -112,7 +112,7 @@ public IReadOnlyCollection ReadChildren(YamlStreamReader reader, KeyVa foreach (var f in toc.Files) _ = Files.Add(f); - return [new FolderReference($"{parentPath}".TrimStart(Path.DirectorySeparatorChar), folderFound, inNav, toc.TableOfContents)]; + return [new TocReference($"{parentPath}".TrimStart(Path.DirectorySeparatorChar), folderFound, inNav, toc.TableOfContents)]; } if (file is not null) From 1c326b58ad6de4b427d91173b40b0e67d06ae6b2 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 18 Mar 2025 20:47:00 +0100 Subject: [PATCH 2/4] relax check for narrative docs too, plays by different rules --- src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs index 855744c30..59fc79298 100644 --- a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs +++ b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs @@ -48,6 +48,11 @@ public record ConfigurationFile : DocumentationFile /// Setting this to true relaxes a few restrictions such as mixing toc references with file and folder reference public bool DevelopmentDocs { get; } + // TODO ensure project key is `docs-content` + private bool IsNarrativeDocs => + _context.Configuration.Project is not null + && _context.Configuration.Project.Equals("Elastic documentation", StringComparison.OrdinalIgnoreCase); + public ConfigurationFile(BuildContext context) : base(context.ConfigurationPath, context.DocumentationSourceDirectory) { @@ -120,7 +125,7 @@ public ConfigurationFile(BuildContext context) var toc = new TableOfContentsConfiguration(this, _context, 0, ""); var children = toc.ReadChildren(reader, entry.Entry); var tocEntries = children.OfType().ToArray(); - if (!DevelopmentDocs && tocEntries.Length > 0 && children.Count != tocEntries.Length) + if (!DevelopmentDocs && !IsNarrativeDocs && tocEntries.Length > 0 && children.Count != tocEntries.Length) reader.EmitError("toc links to other toc sections it may only contain other toc references", entry.Key); TableOfContents = children; Files = toc.Files; //side-effect ripe for refactor From 9f3b8510c0473dafc28e81be01539ab809af3534 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 18 Mar 2025 20:50:52 +0100 Subject: [PATCH 3/4] dotnet format --- src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs index 59fc79298..175b1eb83 100644 --- a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs +++ b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs @@ -51,7 +51,7 @@ public record ConfigurationFile : DocumentationFile // TODO ensure project key is `docs-content` private bool IsNarrativeDocs => _context.Configuration.Project is not null - && _context.Configuration.Project.Equals("Elastic documentation", StringComparison.OrdinalIgnoreCase); + && _context.Configuration.Project.Equals("Elastic documentation", StringComparison.OrdinalIgnoreCase); public ConfigurationFile(BuildContext context) : base(context.ConfigurationPath, context.DocumentationSourceDirectory) @@ -157,6 +157,4 @@ private IReadOnlyCollection InstantiateExtensions() return list.AsReadOnly(); } - - } From fe6477c520e8cb9d10d460e250ade32fd337b7e6 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 18 Mar 2025 20:56:55 +0100 Subject: [PATCH 4/4] reference Project directly --- src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs index 175b1eb83..216ede241 100644 --- a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs +++ b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs @@ -50,8 +50,8 @@ public record ConfigurationFile : DocumentationFile // TODO ensure project key is `docs-content` private bool IsNarrativeDocs => - _context.Configuration.Project is not null - && _context.Configuration.Project.Equals("Elastic documentation", StringComparison.OrdinalIgnoreCase); + Project is not null + && Project.Equals("Elastic documentation", StringComparison.OrdinalIgnoreCase); public ConfigurationFile(BuildContext context) : base(context.ConfigurationPath, context.DocumentationSourceDirectory)