Add initial support for structured settings references (yaml) (#105)

Author: Mpdreamz

docs/source/elastic/reference/index.md

@@ -2,10 +2,7 @@
 title: Automated Settings Reference
 ---
 
-Elastic docs v3 supports automatically generated configuration documentation OOTB.
-Simply supply a yaml spec and corresponding template file and content will be automatically built and updated.
 
-This section includes one example yaml file and two auto-generated outputs based on that file:
 
-* [example `yaml` file](source.md)
-* [generated output](generated.md)
+```{settings} kibana-alerting-action-settings.yml
+```

docs/source/elastic/reference/kibana-alerting-action-settings.yml

@@ -2,14 +2,16 @@
 title: Substitutions
 sub:
   frontmatter_key: "Front Matter Value"
+  a-key-with-dashes: "A key with dashes"
   version: 7.17.0
 ---
 
 Here are some variable substitutions:
 
-| Value               | Source       |
-| ------------------- | ------------ |
-| {{frontmatter_key}} | Front Matter |
+| Variable              | Defined in   |
+|-----------------------|--------------|
+| {{frontmatter_key}}   | Front Matter |
+| {{a-key-with-dashes}} | Front Matter |
 
 Substitutions should work in code blocks too.
 
@@ -20,3 +22,6 @@ shasum -a 512 -c elasticsearch-{{version}}-linux-x86_64.tar.gz.sha512 <1>
 tar -xzf elasticsearch-{{version}}-linux-x86_64.tar.gz
 cd elasticsearch-{{version}}/ <2>
 ```
+
+
+Here is a variable with dashes: {{a-key-with-dashes}}

docs/source/markup/substitutions.md

@@ -4,6 +4,7 @@
 
 using System.IO.Abstractions;
 using Elastic.Markdown.Myst;
+using Elastic.Markdown.Myst.Directives;
 using Markdig.Helpers;
 using Markdig.Parsers;
 
@@ -44,7 +45,7 @@ public static void EmitWarning(this InlineProcessor processor, int line, int col
 		context.Build.Collector.Channel.Write(d);
 	}
 
-	public static void EmitError(this ParserContext context, int line, int column, int length, string message)
+	public static void EmitError(this ParserContext context, int line, int column, int length, string message, Exception? e = null)
 	{
 		if (context.SkipValidation) return;
 		var d = new Diagnostic
@@ -53,7 +54,7 @@ public static void EmitError(this ParserContext context, int line, int column, i
 			File = context.Path.FullName,
 			Column = column,
 			Line = line,
-			Message = message,
+			Message = message + (e != null ? Environment.NewLine + e : string.Empty),
 			Length = length
 		};
 		context.Build.Collector.Channel.Write(d);
@@ -74,13 +75,13 @@ public static void EmitWarning(this ParserContext context, int line, int column,
 		context.Build.Collector.Channel.Write(d);
 	}
 
-	public static void EmitError(this BuildContext context, IFileInfo file, string message)
+	public static void EmitError(this BuildContext context, IFileInfo file, string message, Exception? e = null)
 	{
 		var d = new Diagnostic
 		{
 			Severity = Severity.Error,
 			File = file.FullName,
-			Message = message,
+			Message = message + (e != null ? Environment.NewLine + e : string.Empty),
 		};
 		context.Collector.Channel.Write(d);
 	}
@@ -89,10 +90,42 @@ public static void EmitWarning(this BuildContext context, IFileInfo file, string
 	{
 		var d = new Diagnostic
 		{
-			Severity = Severity.Error,
+			Severity = Severity.Warning,
 			File = file.FullName,
 			Message = message,
 		};
 		context.Collector.Channel.Write(d);
 	}
+
+	public static void EmitError(this DirectiveBlock block, string message, Exception? e = null)
+	{
+		if (block.SkipValidation) return;
+
+		var d = new Diagnostic
+		{
+			Severity = Severity.Error,
+			File = block.CurrentFile.FullName,
+			Line = block.Line + 1,
+			Column = block.Column,
+			Length = block.Directive.Length + 5,
+			Message = message + (e != null ? Environment.NewLine + e : string.Empty),
+		};
+		block.Build.Collector.Channel.Write(d);
+	}
+
+	public static void EmitWarning(this DirectiveBlock block, string message)
+	{
+		if (block.SkipValidation) return;
+
+		var d = new Diagnostic
+		{
+			Severity = Severity.Warning,
+			File = block.CurrentFile.FullName,
+			Line = block.Line + 1,
+			Column = block.Column,
+			Length = block.Directive.Length + 4,
+			Message = message
+		};
+		block.Build.Collector.Channel.Write(d);
+	}
 }

src/Elastic.Markdown/Diagnostics/ProcessorDiagnosticExtensions.cs

@@ -75,7 +75,7 @@ private void ReadDocumentInstructions(MarkdownDocument document)
 		if (document.FirstOrDefault() is YamlFrontMatterBlock yaml)
 		{
 			var raw = string.Join(Environment.NewLine, yaml.Lines.Lines);
-			YamlFrontMatter = FrontMatterParser.Deserialize(raw);
+			YamlFrontMatter = YamlSerialization.Deserialize<YamlFrontMatter>(raw);
 			Title = YamlFrontMatter.Title;
 			NavigationTitle = YamlFrontMatter.NavigationTitle;
 		}

src/Elastic.Markdown/IO/MarkdownFile.cs

@@ -3,8 +3,12 @@
 // See the LICENSE file in the project root for more information
 namespace Elastic.Markdown.Myst.Directives;
 
-public class AdmonitionBlock(DirectiveBlockParser parser, string admonition, Dictionary<string, string> properties)
-	: DirectiveBlock(parser, properties)
+public class AdmonitionBlock(
+	DirectiveBlockParser parser,
+	string admonition,
+	Dictionary<string, string> properties,
+	ParserContext context)
+	: DirectiveBlock(parser, properties, context)
 {
 	public string Admonition => admonition == "admonition" ? Classes?.Trim() ?? "note" : admonition;
 
@@ -36,8 +40,8 @@ public override void FinalizeAndValidate(ParserContext context)
 }
 
 
-public class DropdownBlock(DirectiveBlockParser parser, Dictionary<string, string> properties)
-	: AdmonitionBlock(parser, "admonition", properties)
+public class DropdownBlock(DirectiveBlockParser parser, Dictionary<string, string> properties, ParserContext context)
+	: AdmonitionBlock(parser, "admonition", properties, context)
 {
 	// ReSharper disable once RedundantOverriddenMember
 	public override void FinalizeAndValidate(ParserContext context)

src/Elastic.Markdown/Myst/Directives/AdmonitionBlock.cs

@@ -2,13 +2,14 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.Myst.FrontMatter;
 using Markdig.Syntax;
 
 namespace Elastic.Markdown.Myst.Directives;
 
-public class AppliesBlock(DirectiveBlockParser parser, Dictionary<string, string> properties)
-	: DirectiveBlock(parser, properties)
+public class AppliesBlock(DirectiveBlockParser parser, Dictionary<string, string> properties, ParserContext context)
+	: DirectiveBlock(parser, properties, context)
 {
 	public override string Directive => "mermaid";
 
@@ -64,15 +65,15 @@ public override void FinalizeAndValidate(ParserContext context)
 		}
 
 		if (Deployment is null)
-			EmitError(context, "{applies} block with no product availability specified");
+			this.EmitError("{applies} block with no product availability specified");
 
 		var index = Parent?.IndexOf(this);
 		if (Parent is not null && index > 0)
 		{
 			var i = index - 1 ?? 0;
 			var prevSib = Parent[i];
 			if (prevSib is not HeadingBlock)
-				EmitError(context, "{applies} should follow a heading");
+				this.EmitError("{applies} should follow a heading");
 		}
 
 		bool TryGetAvailability(string key, out ProductAvailability? semVersion)

src/Elastic.Markdown/Myst/Directives/AppliesBlock.cs

@@ -3,8 +3,12 @@
 // See the LICENSE file in the project root for more information
 namespace Elastic.Markdown.Myst.Directives;
 
-public class CodeBlock(DirectiveBlockParser parser, string directive, Dictionary<string, string> properties)
-	: DirectiveBlock(parser, properties)
+public class CodeBlock(
+	DirectiveBlockParser parser,
+	string directive,
+	Dictionary<string, string> properties,
+	ParserContext context)
+	: DirectiveBlock(parser, properties, context)
 {
 	public override string Directive => directive;
 	public string? Caption { get; private set; }

src/Elastic.Markdown/Myst/Directives/CodeBlock.cs

@@ -5,6 +5,7 @@
 // This file is licensed under the BSD-Clause 2 license.
 // See the license.txt file in the project root for more information.
 
+using System.IO.Abstractions;
 using Elastic.Markdown.Diagnostics;
 using Markdig.Helpers;
 using Markdig.Syntax;
@@ -22,10 +23,22 @@ namespace Elastic.Markdown.Myst.Directives;
 /// <param name="parser">The parser used to create this block.</param>
 /// <param name="properties"></param>
 /// <param name="context"></param>
-public abstract class DirectiveBlock(DirectiveBlockParser parser, Dictionary<string, string> properties)
+public abstract class DirectiveBlock(
+	DirectiveBlockParser parser,
+	Dictionary<string, string> properties,
+	ParserContext context
+	)
 	: ContainerBlock(parser), IFencedBlock
 {
-	public IReadOnlyDictionary<string, string> Properties { get; } = properties;
+	protected IReadOnlyDictionary<string, string> Properties { get; } = properties;
+
+	public BuildContext Build { get; } = context.Build;
+
+	public IFileInfo CurrentFile { get; } = context.Path;
+
+	public bool SkipValidation { get; } = context.SkipValidation;
+
+	public abstract string Directive { get; }
 
 	public string? CrossReferenceName  { get; protected set; }
 
@@ -91,13 +104,4 @@ protected bool PropBool(params string[] keys)
 		return default;
 	}
 
-	public abstract string Directive { get; }
-
-	protected void EmitError(ParserContext context, string message) =>
-		context.EmitError(Line + 1, 1, Directive.Length + 4 , message);
-
-	protected void EmitWarning(ParserContext context, string message) =>
-		context.EmitWarning(Line + 1, 1, Directive.Length + 4 , message);
-
-
 }

src/Elastic.Markdown/Myst/Directives/DirectiveBlock.cs

@@ -74,21 +74,21 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor)
 			throw new Exception("Expected parser context to be of type ParserContext");
 
 		if (info.IndexOf("{") == -1)
-		    return new CodeBlock(this, "raw", _admonitionData);
+		    return new CodeBlock(this, "raw", _admonitionData, context);
 
 	    // TODO alternate lookup .NET 9
 	    var directive = info.ToString().Trim(['{', '}', '`']);
 	    if (_unsupportedBlocks.TryGetValue(directive, out var issueId))
-		    return new UnsupportedDirectiveBlock(this, directive, _admonitionData, issueId);
+		    return new UnsupportedDirectiveBlock(this, directive, _admonitionData, issueId, context);
 
 	    if (info.IndexOf("{tab-set}") > 0)
-		    return new TabSetBlock(this, _admonitionData);
+		    return new TabSetBlock(this, _admonitionData, context);
 
 	    if (info.IndexOf("{tab-item}") > 0)
-		    return new TabItemBlock(this, _admonitionData);
+		    return new TabItemBlock(this, _admonitionData, context);
 
 	    if (info.IndexOf("{dropdown}") > 0)
-		    return new DropdownBlock(this, _admonitionData);
+		    return new DropdownBlock(this, _admonitionData, context);
 
 	    if (info.IndexOf("{image}") > 0)
 		    return new ImageBlock(this, _admonitionData, context);
@@ -103,7 +103,7 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor)
 	    // leaving the parsing in until we are confident we don't want this
 	    // for dev-docs
 	    if (info.IndexOf("{mermaid}") > 0)
-		    return new MermaidBlock(this, _admonitionData);
+		    return new MermaidBlock(this, _admonitionData, context);
 
 	    if (info.IndexOf("{include}") > 0)
 			return new IncludeBlock(this, _admonitionData, context);
@@ -112,26 +112,29 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor)
 			return new LiteralIncludeBlock(this, _admonitionData, context);
 
 	    if (info.IndexOf("{applies}") > 0)
-			return new AppliesBlock(this, _admonitionData);
+			return new AppliesBlock(this, _admonitionData, context);
+
+	    if (info.IndexOf("{settings}") > 0)
+			return new SettingsBlock(this, _admonitionData, context);
 
 	    foreach (var admonition in _admonitions)
 	    {
 		    if (info.IndexOf($"{{{admonition}}}") > 0)
-			    return new AdmonitionBlock(this, admonition, _admonitionData);
+			    return new AdmonitionBlock(this, admonition, _admonitionData, context);
 	    }
 
 	    foreach (var version in _versionBlocks)
 	    {
 		    if (info.IndexOf($"{{{version}}}") > 0)
-			    return new VersionBlock(this, version, _admonitionData);
+			    return new VersionBlock(this, version, _admonitionData, context);
 	    }
 
 	    foreach (var code in _codeBlocks)
 	    {
 		    if (info.IndexOf($"{{{code}}}") > 0)
-			    return new CodeBlock(this, code, _admonitionData);
+			    return new CodeBlock(this, code, _admonitionData, context);
 	    }
-	    return new UnknownDirectiveBlock(this, info.ToString(), _admonitionData);
+	    return new UnknownDirectiveBlock(this, info.ToString(), _admonitionData, context);
     }
 
     public override bool Close(BlockProcessor processor, Block block)