Skip to content

Commit aa9a3e8

Browse files
committed
Restrict docset.yml configs that define toc.yml sections to ONLY link to sub toc.yml files (#767)
* Restrict docset.yml configs that define toc.yml sections to ONLY link to sub toc.yml files * relax check for narrative docs too, plays by different rules * dotnet format * reference Project directly
1 parent 9bf69db commit aa9a3e8

File tree

4 files changed

+23
-5
lines changed

4 files changed

+23
-5
lines changed

docs/_docset.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
project: 'doc-builder'
22
max_toc_depth: 2
3+
# indicates this documentation set is not linkable by assembler.
4+
# relaxes a few restrictions around toc building and file placement
5+
dev_docs: true
36
cross_links:
47
- docs-content
58
exclude:

src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,15 @@ public record ConfigurationFile : DocumentationFile
4444
private FeatureFlags? _featureFlags;
4545
public FeatureFlags Features => _featureFlags ??= new FeatureFlags(_features);
4646

47+
/// This is a documentation set that is not linked to by assembler.
48+
/// Setting this to true relaxes a few restrictions such as mixing toc references with file and folder reference
49+
public bool DevelopmentDocs { get; }
50+
51+
// TODO ensure project key is `docs-content`
52+
private bool IsNarrativeDocs =>
53+
Project is not null
54+
&& Project.Equals("Elastic documentation", StringComparison.OrdinalIgnoreCase);
55+
4756
public ConfigurationFile(BuildContext context)
4857
: base(context.ConfigurationPath, context.DocumentationSourceDirectory)
4958
{
@@ -74,6 +83,9 @@ public ConfigurationFile(BuildContext context)
7483
case "max_toc_depth":
7584
MaxTocDepth = int.TryParse(reader.ReadString(entry.Entry), out var maxTocDepth) ? maxTocDepth : 1;
7685
break;
86+
case "dev_docs":
87+
DevelopmentDocs = bool.TryParse(reader.ReadString(entry.Entry), out var devDocs) && devDocs;
88+
break;
7789
case "exclude":
7890
var excludes = YamlStreamReader.ReadStringArray(entry.Entry);
7991
Exclude = [.. excludes.Where(s => !string.IsNullOrEmpty(s)).Select(Glob.Parse)];
@@ -111,8 +123,11 @@ public ConfigurationFile(BuildContext context)
111123
{
112124
case "toc":
113125
var toc = new TableOfContentsConfiguration(this, _context, 0, "");
114-
var entries = toc.ReadChildren(reader, entry.Entry);
115-
TableOfContents = entries;
126+
var children = toc.ReadChildren(reader, entry.Entry);
127+
var tocEntries = children.OfType<TocReference>().ToArray();
128+
if (!DevelopmentDocs && !IsNarrativeDocs && tocEntries.Length > 0 && children.Count != tocEntries.Length)
129+
reader.EmitError("toc links to other toc sections it may only contain other toc references", entry.Key);
130+
TableOfContents = children;
116131
Files = toc.Files; //side-effect ripe for refactor
117132
break;
118133
}
@@ -142,6 +157,4 @@ private IReadOnlyCollection<IDocsBuilderExtension> InstantiateExtensions()
142157

143158
return list.AsReadOnly();
144159
}
145-
146-
147160
}

src/Elastic.Markdown/IO/Configuration/ITocItem.cs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,5 @@ public interface ITocItem;
99
public record FileReference(string Path, bool Found, bool Hidden, IReadOnlyCollection<ITocItem> Children) : ITocItem;
1010

1111
public record FolderReference(string Path, bool Found, bool InNav, IReadOnlyCollection<ITocItem> Children) : ITocItem;
12+
13+
public record TocReference(string Path, bool Found, bool InNav, IReadOnlyCollection<ITocItem> Children) : FolderReference(Path, Found, InNav, Children);

src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ public IReadOnlyCollection<ITocItem> ReadChildren(YamlStreamReader reader, KeyVa
112112
foreach (var f in toc.Files)
113113
_ = Files.Add(f);
114114

115-
return [new FolderReference($"{parentPath}".TrimStart(Path.DirectorySeparatorChar), folderFound, inNav, toc.TableOfContents)];
115+
return [new TocReference($"{parentPath}".TrimStart(Path.DirectorySeparatorChar), folderFound, inNav, toc.TableOfContents)];
116116
}
117117

118118
if (file is not null)

0 commit comments

Comments
 (0)