From 93828ef967ab98dcf8f63d61eb6b64e0cfcd5137 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 13 Nov 2024 14:59:00 +0100 Subject: [PATCH] limit admonitions to attention, caution, note & tip --- .../Myst/Directives/AdmonitionBlock.cs | 5 +- .../Myst/Directives/CodeBlock.cs | 2 +- .../Myst/Directives/DirectiveBlock.cs | 7 ++- .../Myst/Directives/DirectiveBlockParser.cs | 12 +++-- .../Myst/Directives/ImageBlock.cs | 2 + .../Myst/Directives/IncludeBlock.cs | 9 ++-- .../Myst/Directives/MermaidBlock.cs | 2 + .../Myst/Directives/TabSetBlock.cs | 4 ++ .../Myst/Directives/UnknownDirectiveBlock.cs | 2 +- .../Directives/UnsupportedDirectiveBlock.cs | 2 +- .../Myst/Directives/VersionBlock.cs | 2 +- .../Directives/AdmonitionTests.cs | 49 +------------------ .../Directives/AdmonitionUnsupportedTests.cs | 36 ++++++++++++++ 13 files changed, 73 insertions(+), 61 deletions(-) create mode 100644 tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs diff --git a/src/Elastic.Markdown/Myst/Directives/AdmonitionBlock.cs b/src/Elastic.Markdown/Myst/Directives/AdmonitionBlock.cs index 09b511ea7..19ec72704 100644 --- a/src/Elastic.Markdown/Myst/Directives/AdmonitionBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/AdmonitionBlock.cs @@ -7,6 +7,9 @@ public class AdmonitionBlock(DirectiveBlockParser parser, string admonition, Dic : DirectiveBlock(parser, properties) { public string Admonition => admonition == "admonition" ? Classes?.Trim() ?? "note" : admonition; + + public override string Directive => Admonition; + public string? Classes { get; protected set; } public string? CrossReferenceName { get; private set; } public bool? DropdownOpen { get; private set; } @@ -15,7 +18,7 @@ public string Title { get { - var t = Admonition == "seealso" ? "see also" : Admonition; + var t = Admonition; var title = Thread.CurrentThread.CurrentCulture.TextInfo.ToTitleCase(t); if (admonition is "admonition" && !string.IsNullOrEmpty(Arguments)) title = Arguments; diff --git a/src/Elastic.Markdown/Myst/Directives/CodeBlock.cs b/src/Elastic.Markdown/Myst/Directives/CodeBlock.cs index 515870cfb..306c0ea7f 100644 --- a/src/Elastic.Markdown/Myst/Directives/CodeBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/CodeBlock.cs @@ -6,7 +6,7 @@ namespace Elastic.Markdown.Myst.Directives; public class CodeBlock(DirectiveBlockParser parser, string directive, Dictionary properties) : DirectiveBlock(parser, properties) { - public string Directive => directive; + public override string Directive => directive; public string? Caption { get; private set; } public string? CrossReferenceName { get; private set; } diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlock.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlock.cs index ba31155f6..579e4863f 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveBlock.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 Elastic.Markdown.Diagnostics; using Markdig.Helpers; using Markdig.Syntax; @@ -24,7 +25,6 @@ namespace Elastic.Markdown.Myst.Directives; public abstract class DirectiveBlock(DirectiveBlockParser parser, Dictionary properties) : ContainerBlock(parser), IFencedBlock { - public IReadOnlyDictionary Properties { get; } = properties; /// @@ -89,5 +89,10 @@ 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); + } diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs index bfdf1902d..a200533c1 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs @@ -30,9 +30,7 @@ public DirectiveBlockParser() private Dictionary _admonitionData = new(); - private readonly string[] _admonitions = [ - "admonition", "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "seealso" - ]; + private readonly string[] _admonitions = [ "attention", "caution", "note", "tip" ]; private readonly string[] _versionBlocks = [ "versionadded", "versionchanged", "versionremoved", "deprecated" ]; @@ -59,7 +57,13 @@ public DirectiveBlockParser() { "sidebar", 4 }, { "code-cell", 8 }, - + { "admonition", 3 }, + { "attention", 3 }, + { "danger", 3 }, + { "error", 3 }, + { "hint", 3 }, + { "important", 3 }, + { "seealso", 3 } }.ToFrozenDictionary(); protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor) diff --git a/src/Elastic.Markdown/Myst/Directives/ImageBlock.cs b/src/Elastic.Markdown/Myst/Directives/ImageBlock.cs index 96e28b02e..947c5697c 100644 --- a/src/Elastic.Markdown/Myst/Directives/ImageBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/ImageBlock.cs @@ -6,6 +6,8 @@ namespace Elastic.Markdown.Myst.Directives; public class ImageBlock(DirectiveBlockParser parser, Dictionary properties, ParserContext context) : DirectiveBlock(parser, properties) { + public override string Directive => "image"; + public BuildContext Build { get; } = context.Build; /// diff --git a/src/Elastic.Markdown/Myst/Directives/IncludeBlock.cs b/src/Elastic.Markdown/Myst/Directives/IncludeBlock.cs index be25ca66c..edd35510c 100644 --- a/src/Elastic.Markdown/Myst/Directives/IncludeBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/IncludeBlock.cs @@ -9,6 +9,8 @@ namespace Elastic.Markdown.Myst.Directives; public class IncludeBlock(DirectiveBlockParser parser, Dictionary properties, ParserContext context) : DirectiveBlock(parser, properties) { + public override string Directive => "include"; + public BuildContext Build { get; } = context.Build; public IFileSystem FileSystem { get; } = context.Build.ReadFileSystem; @@ -21,8 +23,6 @@ public class IncludeBlock(DirectiveBlockParser parser, Dictionary properties, ParserContext context) : base(parser, properties, context) => Literal = true; - protected override string Directive { get; } = "literalinclude"; + public override string Directive => "literalinclude"; + } diff --git a/src/Elastic.Markdown/Myst/Directives/MermaidBlock.cs b/src/Elastic.Markdown/Myst/Directives/MermaidBlock.cs index 39fad7af1..73fd0d450 100644 --- a/src/Elastic.Markdown/Myst/Directives/MermaidBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/MermaidBlock.cs @@ -6,6 +6,8 @@ namespace Elastic.Markdown.Myst.Directives; public class MermaidBlock(DirectiveBlockParser parser, Dictionary properties) : DirectiveBlock(parser, properties) { + public override string Directive => "mermaid"; + public override void FinalizeAndValidate(ParserContext context) { } diff --git a/src/Elastic.Markdown/Myst/Directives/TabSetBlock.cs b/src/Elastic.Markdown/Myst/Directives/TabSetBlock.cs index 465bf2362..0dceaf5f5 100644 --- a/src/Elastic.Markdown/Myst/Directives/TabSetBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/TabSetBlock.cs @@ -9,6 +9,8 @@ namespace Elastic.Markdown.Myst.Directives; public class TabSetBlock(DirectiveBlockParser parser, Dictionary properties) : DirectiveBlock(parser, properties) { + public override string Directive => "tab-set"; + public int Index { get; set; } public override void FinalizeAndValidate(ParserContext context) => Index = FindIndex(); @@ -24,6 +26,8 @@ public int FindIndex() public class TabItemBlock(DirectiveBlockParser parser, Dictionary properties) : DirectiveBlock(parser, properties) { + public override string Directive => "tab-set-item"; + public string Title { get; set; } = default!; public int Index { get; set; } public int TabSetIndex { get; set; } diff --git a/src/Elastic.Markdown/Myst/Directives/UnknownDirectiveBlock.cs b/src/Elastic.Markdown/Myst/Directives/UnknownDirectiveBlock.cs index 050190be5..f0c8a812a 100644 --- a/src/Elastic.Markdown/Myst/Directives/UnknownDirectiveBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/UnknownDirectiveBlock.cs @@ -7,7 +7,7 @@ namespace Elastic.Markdown.Myst.Directives; public class UnknownDirectiveBlock(DirectiveBlockParser parser, string directive, Dictionary properties) : DirectiveBlock(parser, properties) { - public string Directive => directive; + public override string Directive => directive; public override void FinalizeAndValidate(ParserContext context) { diff --git a/src/Elastic.Markdown/Myst/Directives/UnsupportedDirectiveBlock.cs b/src/Elastic.Markdown/Myst/Directives/UnsupportedDirectiveBlock.cs index f0700bb5f..47cbef938 100644 --- a/src/Elastic.Markdown/Myst/Directives/UnsupportedDirectiveBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/UnsupportedDirectiveBlock.cs @@ -9,7 +9,7 @@ namespace Elastic.Markdown.Myst.Directives; public class UnsupportedDirectiveBlock(DirectiveBlockParser parser, string directive, Dictionary properties, int issueId) : DirectiveBlock(parser, properties) { - public string Directive => directive; + public override string Directive => directive; public string IssueUrl => $"https://github.com/elastic/docs-builder/issues/{issueId}"; diff --git a/src/Elastic.Markdown/Myst/Directives/VersionBlock.cs b/src/Elastic.Markdown/Myst/Directives/VersionBlock.cs index 4429098e4..b145f502e 100644 --- a/src/Elastic.Markdown/Myst/Directives/VersionBlock.cs +++ b/src/Elastic.Markdown/Myst/Directives/VersionBlock.cs @@ -6,7 +6,7 @@ namespace Elastic.Markdown.Myst.Directives; public class VersionBlock(DirectiveBlockParser parser, string directive, Dictionary properties) : DirectiveBlock(parser, properties) { - public string Directive => directive; + public override string Directive => directive; public string Class => directive.Replace("version", ""); public string Title diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs index 913c7c5b6..814a840c4 100644 --- a/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs +++ b/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs @@ -23,46 +23,18 @@ A regular paragraph. public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be(directive); } -public class AttentionTests(ITestOutputHelper output) : AdmonitionTests(output, "attention") -{ - [Fact] - public void SetsTitle() => Block!.Title.Should().Be("Attention"); -} public class CautionTests(ITestOutputHelper output) : AdmonitionTests(output, "caution") { [Fact] public void SetsTitle() => Block!.Title.Should().Be("Caution"); } -public class DangerTests(ITestOutputHelper output) : AdmonitionTests(output, "danger") -{ - [Fact] - public void SetsTitle() => Block!.Title.Should().Be("Danger"); -} -public class ErrorTests(ITestOutputHelper output) : AdmonitionTests(output, "error") -{ - [Fact] - public void SetsTitle() => Block!.Title.Should().Be("Error"); -} -public class HintTests(ITestOutputHelper output) : AdmonitionTests(output, "hint") -{ - [Fact] - public void SetsTitle() => Block!.Title.Should().Be("Hint"); -} -public class ImportantTests(ITestOutputHelper output) : AdmonitionTests(output, "important") -{ - [Fact] - public void SetsTitle() => Block!.Title.Should().Be("Important"); -} + public class NoteTests(ITestOutputHelper output) : AdmonitionTests(output, "note") { [Fact] public void SetsTitle() => Block!.Title.Should().Be("Note"); } -public class SeeAlsoTests(ITestOutputHelper output) : AdmonitionTests(output, "seealso") -{ - [Fact] - public void SetsTitle() => Block!.Title.Should().Be("See Also"); -} + public class TipTests(ITestOutputHelper output) : AdmonitionTests(output, "tip") { [Fact] @@ -85,23 +57,6 @@ A regular paragraph. public void SetsCustomTitle() => Block!.Title.Should().Be("Note This is my custom note"); } -public class AdmonitionTitleTests(ITestOutputHelper output) : DirectiveTest(output, -""" -```{admonition} This is my custom note -This is an attention block -``` -A regular paragraph. -""" -) -{ - [Fact] - public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be("note"); - - [Fact] - public void SetsCustomTitle() => Block!.Title.Should().Be("This is my custom note"); -} - - public class DropdownTitleTests(ITestOutputHelper output) : DirectiveTest(output, """ ```{dropdown} This is my custom dropdown diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs new file mode 100644 index 000000000..66e24a5d6 --- /dev/null +++ b/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs @@ -0,0 +1,36 @@ +// Licensed to Elasticsearch B.V under one or more agreements. +// 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.Myst.Directives; +using FluentAssertions; +using Xunit.Abstractions; + +namespace Elastic.Markdown.Tests.Directives; + +public abstract class AdmonitionUnsupportedTests(ITestOutputHelper output, string directive) + : DirectiveTest(output, + $$""" + ```{{{directive}}} + This is an attention block + ``` + A regular paragraph. + """ + ) +{ + [Fact] + public void ParsesAsUnknown() => Block.Should().NotBeNull(); + + [Fact] + public void SetsCorrectDirective() => Block!.Directive.Should().Be(directive); +} + +// ReSharper disable UnusedType.Global +public class AttentionTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "attention"); +public class DangerTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "danger"); +public class ErrorTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "error"); +public class HintTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "hint"); +public class ImportantTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "important"); +public class SeeAlsoTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "seealso"); +public class AdmonitionTitleTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "admonition"); +// ReSharper restore UnusedType.Global