Skip to content

Commit 0d56f79

Browse files
yufeihyufeih
committed
refactor: strongly type plantuml config
1 parent 0cfc17f commit 0d56f79

File tree

12 files changed

+133
-178
lines changed

12 files changed

+133
-178
lines changed

‎src/Docfx.MarkdigEngine.Extensions/MarkdownContext.cs‎

Lines changed: 1 addition & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,13 +36,6 @@ public class MarkdownContext
3636
/// <returns>Image url bound to the path</returns>
3737
public delegate string GetImageLinkDelegate(string path, MarkdownObject origin, string altText);
3838

39-
/// <summary>
40-
/// Allows configuration of extensions
41-
/// </summary>
42-
/// <param name="extension">Name of the extension being configured</param>
43-
/// <returns>Object representing the configuration for the extension</returns>
44-
public delegate object GetExtensionConfigurationDelegate(string extension);
45-
4639
/// <summary>
4740
/// Reads a file as text.
4841
/// </summary>
@@ -58,11 +51,6 @@ public class MarkdownContext
5851
/// </summary>
5952
public GetImageLinkDelegate GetImageLink { get; }
6053

61-
/// <summary>
62-
/// Get the configuration for a given extension
63-
/// </summary>
64-
public GetExtensionConfigurationDelegate GetExtensionConfiguration { get; }
65-
6654
/// <summary>
6755
/// Log info
6856
/// </summary>
@@ -98,14 +86,12 @@ public MarkdownContext(
9886
LogActionDelegate logError = null,
9987
ReadFileDelegate readFile = null,
10088
GetLinkDelegate getLink = null,
101-
GetImageLinkDelegate getImageLink = null,
102-
GetExtensionConfigurationDelegate getConfig = null)
89+
GetImageLinkDelegate getImageLink = null)
10390
{
10491
_getToken = getToken ?? (_ => null);
10592
ReadFile = readFile ?? ((a, b) => (a, a));
10693
GetLink = getLink ?? ((a, b) => a);
10794
GetImageLink = getImageLink ?? ((a, b, c) => a);
108-
GetExtensionConfiguration = getConfig ?? (_ => null);
10995
LogInfo = logInfo ?? ((a, b, c, d) => { });
11096
LogSuggestion = logSuggestion ?? ((a, b, c, d) => { });
11197
LogWarning = logWarning ?? ((a, b, c, d) => { });

‎src/Docfx.MarkdigEngine.Extensions/MarkdownExtensions.cs‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ namespace Docfx.MarkdigEngine.Extensions;
1111

1212
public static class MarkdownExtensions
1313
{
14-
public static MarkdownPipelineBuilder UseDocfxExtensions(this MarkdownPipelineBuilder pipeline, MarkdownContext context)
14+
public static MarkdownPipelineBuilder UseDocfxExtensions(
15+
this MarkdownPipelineBuilder pipeline, MarkdownContext context,
16+
Dictionary<string, string> notes = null, PlantUmlOptions plantUml = null)
1517
{
1618
return pipeline
1719
.UseMathematics()
@@ -24,7 +26,7 @@ public static MarkdownPipelineBuilder UseDocfxExtensions(this MarkdownPipelineBu
2426
.UseIncludeFile(context)
2527
.UseCodeSnippet(context)
2628
.UseDFMCodeInfoPrefix()
27-
.UseQuoteSectionNote(context)
29+
.UseQuoteSectionNote(context, notes)
2830
.UseXref()
2931
.UseEmojiAndSmiley(false)
3032
.UseTabGroup(context)
@@ -35,7 +37,7 @@ public static MarkdownPipelineBuilder UseDocfxExtensions(this MarkdownPipelineBu
3537
.UseTripleColon(context)
3638
.UseNoloc()
3739
.UseResolveLink(context)
38-
.UsePlantUml(context)
40+
.UsePlantUml(context, plantUml)
3941
.RemoveUnusedExtensions();
4042
}
4143

@@ -100,9 +102,9 @@ public static MarkdownPipelineBuilder UseDFMCodeInfoPrefix(this MarkdownPipeline
100102
return pipeline;
101103
}
102104

103-
public static MarkdownPipelineBuilder UseQuoteSectionNote(this MarkdownPipelineBuilder pipeline, MarkdownContext context)
105+
public static MarkdownPipelineBuilder UseQuoteSectionNote(this MarkdownPipelineBuilder pipeline, MarkdownContext context, Dictionary<string, string> notes = null)
104106
{
105-
pipeline.Extensions.AddIfNotAlready(new QuoteSectionNoteExtension(context));
107+
pipeline.Extensions.AddIfNotAlready(new QuoteSectionNoteExtension(context, notes));
106108
return pipeline;
107109
}
108110

@@ -112,9 +114,9 @@ public static MarkdownPipelineBuilder UseLineNumber(this MarkdownPipelineBuilder
112114
return pipeline;
113115
}
114116

115-
public static MarkdownPipelineBuilder UsePlantUml(this MarkdownPipelineBuilder pipeline, MarkdownContext context)
117+
public static MarkdownPipelineBuilder UsePlantUml(this MarkdownPipelineBuilder pipeline, MarkdownContext context, PlantUmlOptions options = null)
116118
{
117-
pipeline.Extensions.AddIfNotAlready(new PlantUmlExtension(context));
119+
pipeline.Extensions.AddIfNotAlready(new PlantUmlExtension(context, options));
118120
return pipeline;
119121
}
120122

‎src/Docfx.MarkdigEngine.Extensions/PlantUml/PlantUmlCodeBlockRenderer.cs‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,31 @@ namespace Docfx.MarkdigEngine.Extensions;
1111
/// An HTML renderer for a <see cref="CodeBlock"/> and <see cref="FencedCodeBlock"/>.
1212
/// </summary>
1313
/// <seealso cref="HtmlObjectRenderer{CodeBlock}" />
14-
public class CustomCodeBlockRenderer : CodeBlockRenderer
14+
class PlantUmlCodeBlockRenderer : CodeBlockRenderer
1515
{
1616
private readonly MarkdownContext _context;
17-
private readonly DocfxPlantUmlSettings _settings;
17+
private readonly PlantUmlSettings _settings;
18+
private readonly OutputFormat _outputFormat;
1819
private readonly RendererFactory rendererFactory;
1920

2021
/// <summary>
2122
/// Initializes a new instance of the <see cref="CodeBlockRenderer"/> class.
2223
/// </summary>
2324
/// <param name="context"></param>
2425
/// <param name="settings"></param>
25-
public CustomCodeBlockRenderer(MarkdownContext context, DocfxPlantUmlSettings settings)
26+
public PlantUmlCodeBlockRenderer(MarkdownContext context, PlantUmlOptions settings)
2627
{
2728
_context = context;
28-
_settings = settings;
29+
_settings = new()
30+
{
31+
Delimitor = settings.Delimitor,
32+
RenderingMode = settings.RenderingMode,
33+
RemoteUrl = settings.RemoteUrl,
34+
JavaPath = settings.JavaPath,
35+
LocalGraphvizDotPath = settings.LocalGraphvizDotPath,
36+
LocalPlantUmlPath = settings.LocalPlantUmlPath,
37+
};
38+
_outputFormat = settings.OutputFormat;
2939

3040
rendererFactory = new RendererFactory();
3141
}
@@ -43,10 +53,10 @@ protected override void Write(HtmlRenderer renderer, CodeBlock obj)
4353

4454
try
4555
{
46-
byte[] output = plantUmlRenderer.Render(plantUmlCode, _settings.OutputFormat);
56+
byte[] output = plantUmlRenderer.Render(plantUmlCode, _outputFormat);
4757

4858
renderer.EnsureLine();
49-
renderer.Write(FormatOutput(_settings.OutputFormat, output));
59+
renderer.Write(FormatOutput(_outputFormat, output));
5060
renderer.EnsureLine();
5161
}
5262
catch (RenderingException ex)

‎src/Docfx.MarkdigEngine.Extensions/PlantUml/PlantUmlExtension.cs‎

Lines changed: 31 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,52 @@
1+
using System.Text.Json.Serialization;
12
using Markdig;
23
using Markdig.Renderers;
34
using Markdig.Renderers.Html;
5+
using Newtonsoft.Json;
46
using PlantUml.Net;
57

68
namespace Docfx.MarkdigEngine.Extensions;
79

8-
public class DocfxPlantUmlSettings : PlantUmlSettings
10+
public class PlantUmlOptions
911
{
10-
public DocfxPlantUmlSettings() : base()
11-
{
12-
}
12+
[JsonProperty("javaPath")]
13+
[JsonPropertyName("javaPath")]
14+
public string JavaPath { get; set; }
1315

14-
public DocfxPlantUmlSettings(IReadOnlyDictionary<string, string> config) : this()
15-
{
16-
if (config.TryGetValue("remoteUrl", out var url))
17-
RemoteUrl = url;
18-
if (config.TryGetValue("outputFormat", out var format))
19-
OutputFormat = Enum.Parse<OutputFormat>(format, true);
20-
if (config.TryGetValue("javaPath", out var path))
21-
JavaPath = path;
22-
if (config.TryGetValue("localPlantUmlPath", out path))
23-
LocalPlantUmlPath = path;
24-
if (config.TryGetValue("localGraphvizDotPath", out path))
25-
LocalGraphvizDotPath = path;
26-
if (config.TryGetValue("renderingMode", out var renderMode))
27-
RenderingMode = Enum.Parse<RenderingMode>(renderMode, true);
28-
}
16+
[JsonProperty("remoteUrl")]
17+
[JsonPropertyName("remoteUrl")]
18+
public string RemoteUrl { get; set; }
19+
20+
[JsonProperty("localPlantUmlPath")]
21+
[JsonPropertyName("localPlantUmlPath")]
22+
public string LocalPlantUmlPath { get; set; }
2923

24+
[JsonProperty("localGraphvizDotPath")]
25+
[JsonPropertyName("localGraphvizDotPath")]
26+
public string LocalGraphvizDotPath { get; set; }
27+
28+
[JsonProperty("renderingMode")]
29+
[JsonPropertyName("renderingMode")]
30+
public RenderingMode RenderingMode { get; set; }
31+
32+
[JsonProperty("delimitor")]
33+
[JsonPropertyName("delimitor")]
34+
public string Delimitor { get; set; }
35+
36+
[JsonProperty("outputFormat")]
37+
[JsonPropertyName("outputFormat")]
3038
public OutputFormat OutputFormat { get; set; } = OutputFormat.Svg;
3139
}
3240

3341
internal class PlantUmlExtension : IMarkdownExtension
3442
{
3543
private readonly MarkdownContext _context;
36-
private readonly DocfxPlantUmlSettings _settings;
44+
private readonly PlantUmlOptions _settings;
3745

38-
public PlantUmlExtension(MarkdownContext context)
46+
public PlantUmlExtension(MarkdownContext context, PlantUmlOptions settings)
3947
{
4048
_context = context;
41-
_settings = new();
42-
43-
if (_context.GetExtensionConfiguration("PlantUml") is Dictionary<string, string> config)
44-
_settings = new DocfxPlantUmlSettings(config);
49+
_settings = settings ?? new();
4550
}
4651

4752
public void Setup(MarkdownPipelineBuilder pipeline)
@@ -52,7 +57,7 @@ public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
5257
{
5358
if (renderer is HtmlRenderer { ObjectRenderers: not null } htmlRenderer)
5459
{
55-
var customRenderer = new CustomCodeBlockRenderer(_context, _settings);
60+
var customRenderer = new PlantUmlCodeBlockRenderer(_context, _settings);
5661
var renderers = htmlRenderer.ObjectRenderers;
5762

5863
if (renderers.Contains<CodeBlockRenderer>())

‎src/Docfx.MarkdigEngine.Extensions/QuoteSectionNote/QuoteSectionNoteExtension.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,13 @@ public class QuoteSectionNoteExtension : IMarkdownExtension
2222
["CAUTION"] = "CAUTION",
2323
};
2424

25-
public QuoteSectionNoteExtension(MarkdownContext context)
25+
public QuoteSectionNoteExtension(MarkdownContext context, Dictionary<string, string> notes)
2626
{
2727
_context = context;
2828

29-
if (_context.GetExtensionConfiguration("Alerts") is Dictionary<string, string> config)
29+
if (notes != null)
3030
{
31-
foreach (var (key, value) in config)
31+
foreach (var (key, value) in notes)
3232
_notes[key] = value;
3333
}
3434
}

‎src/Docfx.MarkdigEngine/MarkdigMarkdownService.cs‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,7 @@ public MarkdigMarkdownService(
3434
(code, message, origin, line) => Logger.LogError(message, null, InclusionContext.File.ToString(), line?.ToString(), code),
3535
ReadFile,
3636
GetLink,
37-
GetImageLink,
38-
GetExtensionConfiguration);
37+
GetImageLink);
3938
}
4039

4140
public MarkupResult Markup(string content, string filePath)
@@ -187,8 +186,6 @@ private static string GetLink(string path, MarkdownObject origin)
187186
return path;
188187
}
189188

190-
private object GetExtensionConfiguration(string extension) => _parameters.GetExtensionConfiguration(extension);
191-
192189
private static string GetImageLink(string href, MarkdownObject origin, string altText) => GetLink(href, origin);
193190

194191
private static void ReportDependency(RelativePath filePathToDocset, string parentFileDirectoryToDocset)

‎src/Docfx.Plugins/MarkdownServiceParameters.cs‎ renamed to ‎src/Docfx.MarkdigEngine/MarkdownServiceParameters.cs‎

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33

44
using System.Collections.Immutable;
55
using System.Text.Json.Serialization;
6+
using Docfx.MarkdigEngine.Extensions;
67
using Newtonsoft.Json;
78

89
namespace Docfx.Plugins;
@@ -41,7 +42,7 @@ public class MarkdownServiceProperties
4142
/// </summary>
4243
[JsonProperty("plantUml")]
4344
[JsonPropertyName("plantUml")]
44-
public Dictionary<string, string> PlantUml { get; set; }
45+
public PlantUmlOptions PlantUml { get; set; }
4546
}
4647

4748
public class MarkdownServiceParameters
@@ -50,16 +51,4 @@ public class MarkdownServiceParameters
5051
public string TemplateDir { get; set; }
5152
public MarkdownServiceProperties Extensions { get; set; } = new();
5253
public ImmutableDictionary<string, string> Tokens { get; set; } = ImmutableDictionary<string, string>.Empty;
53-
54-
public object GetExtensionConfiguration(string extension)
55-
{
56-
if (!string.IsNullOrEmpty(extension) && Extensions != null)
57-
{
58-
var property = typeof(MarkdownServiceProperties).GetProperty(extension);
59-
if (property != null)
60-
return property.GetValue(Extensions);
61-
}
62-
63-
return null;
64-
}
6554
}

‎test/Docfx.MarkdigEngine.Extensions.Tests/PlantUmlTest.cs‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,10 @@ public void TestRenderSvg_SequenceDiagram()
2222
<div class="lang-plantUml"><?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="120px" preserveAspectRatio="none" style="width:113px;height:120px;background:#FFFFFF;" version="1.1" viewBox="0 0 113 120" width="113px" zoomAndPan="magnify"><defs/><g><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="26" x2="26" y1="36.2969" y2="85.4297"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="82" x2="82" y1="36.2969" y2="85.4297"/><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="43" x="5" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="29" x="12" y="24.9951">Bob</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="43" x="5" y="84.4297"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="29" x="12" y="104.4248">Bob</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="49" x="58" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="35" x="65" y="24.9951">Alice</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="49" x="58" y="84.4297"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="35" x="65" y="104.4248">Alice</text><polygon fill="#181818" points="70.5,63.4297,80.5,67.4297,70.5,71.4297,74.5,67.4297" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="26.5" x2="76.5" y1="67.4297" y2="67.4297"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="30" x="33.5" y="62.3638">hello</text><!--SRC=[SyfFKj2rKt3CoKnELR1Io4ZDoSa70000]--></g></svg></div>
2323
""";
2424

25-
TestUtility.VerifyMarkup(source, expected, extensionConfiguration:
26-
new Dictionary<string, string>
27-
{
28-
{ "outputFormat", "svg"},
29-
{ "remoteUrl", "https://www.plantuml.com/plantuml" }
30-
});
25+
TestUtility.VerifyMarkup(source, expected, plantUml: new()
26+
{
27+
OutputFormat = PlantUml.Net.OutputFormat.Svg,
28+
RemoteUrl = "https://www.plantuml.com/plantuml",
29+
});
3130
}
3231
}

‎test/Docfx.MarkdigEngine.Extensions.Tests/QuoteSectionNoteTest.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -480,7 +480,7 @@ public void QuoteSectionNoteTest_ExtensionConfiguration()
480480
<p>This is a custom REVIEW section</p>
481481
</div>
482482
";
483-
TestUtility.VerifyMarkup(source, expected, extensionConfiguration:
483+
TestUtility.VerifyMarkup(source, expected, notes:
484484
new Dictionary<string, string>
485485
{
486486
{ "TODO", "alert alert-secondary" },

‎test/Docfx.MarkdigEngine.Extensions.Tests/TestUtility.cs‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
using Docfx.MarkdigEngine.Extensions;
55
using Markdig;
66
using Markdig.Syntax;
7-
using Newtonsoft.Json.Linq;
87
using Xunit;
98

109
namespace Docfx.MarkdigEngine.Tests;
@@ -20,9 +19,9 @@ public static void VerifyMarkup(
2019
string filePath = "test.md",
2120
Dictionary<string, string> tokens = null,
2221
Dictionary<string, string> files = null,
23-
Action<MarkdownObject> verifyAST = null,
2422
IEnumerable<string> optionalExtensions = null,
25-
object extensionConfiguration = null)
23+
Dictionary<string, string> notes = null,
24+
PlantUmlOptions plantUml = null)
2625
{
2726
errors ??= Array.Empty<string>();
2827
tokens ??= new Dictionary<string, string>();
@@ -38,11 +37,10 @@ public static void VerifyMarkup(
3837
logSuggestion: Log("suggestion"),
3938
logWarning: Log("warning"),
4039
logError: Log("error"),
41-
readFile: ReadFile,
42-
getConfig: _ => extensionConfiguration);
40+
readFile: ReadFile);
4341

4442
var pipelineBuilder = new MarkdownPipelineBuilder()
45-
.UseDocfxExtensions(markdownContext)
43+
.UseDocfxExtensions(markdownContext, notes, plantUml)
4644
.UseYamlFrontMatter()
4745
.UseOptionalExtensions(optionalExtensions);
4846

0 commit comments

Comments
 (0)