Update to maml rendered to pad example titles issue #119 (#322)

* Updated maml generation to pad example header #119

* Updated change log

* Fix FoolLoop tests

Author: BernieWhite

CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 
 * Clean up trailing whitespace during markdown generation [#225](https://github.com/PowerShell/platyPS/issues/225)
 * Preserve line breaks after headers when Update-MarkdownHelp is used [#319](https://github.com/PowerShell/platyPS/issues/319)
+* MAML generation now pads example titles with dash (-) to improve readability [#119](https://github.com/PowerShell/platyPS/issues/119)
 
 ## 0.8.3
 

src/Markdown.MAML/Renderer/MamlRenderer.cs

@@ -19,6 +19,9 @@ public class MamlRenderer
         private static XNamespace devNS = XNamespace.Get("http://schemas.microsoft.com/maml/dev/2004/10");
         private static XNamespace msHelpNS = XNamespace.Get("http://msdn.microsoft.com/mshelp");
 
+        private static char examplePadChar = '-';
+        private static char space = ' ';
+
         /// <summary>
         /// 
         /// </summary>
@@ -161,7 +164,7 @@ private static XElement CreateOutput(MamlInputOutput output)
         private static XElement CreateExample(MamlExample example)
         {
             return new XElement(commandNS + "example",
-                    new XElement(mamlNS + "title", example.Title),
+                    new XElement(mamlNS + "title", PadExampleTitle(example.Title)),
                     new XElement(devNS + "code", example.Code),
                     new XElement(devNS + "remarks", GenerateParagraphs(example.Remarks)));
         }
@@ -189,6 +192,30 @@ private static XElement CreateLink(MamlLink link)
                     new XElement(mamlNS + "uri", uriValue));
         }
 
+        /// <summary>
+        /// Generate (-) padding for example title
+        /// </summary>
+        /// <param name="title">The title to pa.</param>
+        /// <returns>The title padded by dashes</returns>
+        private static string PadExampleTitle(string title)
+        {
+            // Filter out edge cases where title is too long or empty
+            if (string.IsNullOrWhiteSpace(title) || title.Length >= 62)
+            {
+                return title;
+            }
+
+            // Pad example title with dash (-) to increase readability up to 64 characters
+
+            int padLength = (64 - title.Length - 2) / 2;
+
+            return title
+                .PadLeft(title.Length + 1, space)
+                .PadRight(title.Length + 2, space)
+                .PadLeft(title.Length + 2 + padLength, examplePadChar)
+                .PadRight(title.Length + 2 + 2 * padLength, examplePadChar);
+        }
+
         private static string ConvertPSTypeToMamlType(MamlParameter parameter)
         {
             if (parameter.Type == null)

src/Markdown.MAML/Renderer/Markdownv2Renderer.cs

@@ -269,7 +269,6 @@ private string JoinWithComma(IEnumerable<string> args)
 
         private bool ShouldBreak(SectionFormatOption formatOption)
         {
-            // If the line break flag is set return true.
             return formatOption.HasFlag(SectionFormatOption.LineBreakAfterHeader);
         }
 
@@ -345,7 +344,7 @@ private void AddExamples(MamlCommand command)
             {
                 var extraNewLine = ShouldBreak(example.FormatOption);
 
-                AddHeader(ModelTransformerBase.EXAMPLE_HEADING_LEVEL, example.Title, extraNewLine: extraNewLine);
+                AddHeader(ModelTransformerBase.EXAMPLE_HEADING_LEVEL, GetExampleTitle(example.Title), extraNewLine: extraNewLine);
 
                 if (!string.IsNullOrEmpty(example.Introduction))
                 {
@@ -364,12 +363,23 @@ private void AddExamples(MamlCommand command)
             }
         }
 
+        private static string GetExampleTitle(string title)
+        {
+            var match = Regex.Match(title, @"^(-| ){0,}(?<title>([^\f\n\r\t\v\x85\p{Z}-][^\f\n\r\t\v\x85]+[^\f\n\r\t\v\x85\p{Z}-]))(-| ){0,}$");
+            
+            if (match.Success)
+            {
+                return match.Groups["title"].Value;
+            }
+
+            return title;
+        }
+
         public static string GetSyntaxString(MamlCommand command, MamlSyntax syntax)
         {
             return GetSyntaxString(command, syntax, DEFAULT_SYNTAX_WIDTH);
         }
 
-
         public static string GetSyntaxString(MamlCommand command, MamlSyntax syntax, int maxSyntaxWidth)
         {
             // TODO: we may want to add ParameterValueGroup info here,

src/Markdown.MAML/Transformer/MamlModelMerger.cs

@@ -214,7 +214,6 @@ private void MergeParameters(MamlCommand result, MamlCommand metadataModel, Maml
                             _cmdletUpdated = true;
                         }
 
-                        // Update the parameter with the merged in FormatOption
                         param.FormatOption = strParam.FormatOption;
                     }
 

test/Markdown.MAML.Test/EndToEnd/EndToEndTests.cs

@@ -12,12 +12,28 @@ namespace Markdown.MAML.Test.EndToEnd
     public class EndToEndTests
     {
         [Fact]
-        public void ProduceNameAndSynopsis()
+        public void ProduceMamlFromMarkdown()
         {
             string maml = MarkdownStringToMamlString(@"
 # Get-Foo
 ## Synopsis
 This is Synopsis
+## Examples
+### Example 1
+```
+PS C:\> Update-MarkdownHelp
+```
+
+This is example 1 remark.
+
+### Example 2: With a long title
+This is an example description.
+
+```
+PS C:\> Update-MarkdownHelp
+```
+
+This is example 2 remark.
 ");
             string[] name = GetXmlContent(maml, "/msh:helpItems/command:command/command:details/command:name");
             Assert.Equal(1, name.Length);
@@ -26,6 +42,13 @@ This is Synopsis
             string[] synopsis = GetXmlContent(maml, "/msh:helpItems/command:command/command:details/maml:description/maml:para");
             Assert.Equal(1, synopsis.Length);
             Assert.Equal("This is Synopsis", synopsis[0]);
+
+            // Check that example title is reproduced with dash (-) padding
+            string[] example = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:examples/command:example/maml:title");
+            Assert.Equal(63, example[0].Length);
+            Assert.Equal(64, example[1].Length);
+            Assert.Matches($"^-+ Example 1 -+$", example[0]);
+            Assert.Matches($"^-+ Example 2: With a long title -+$", example[1]);
         }
 
         [Fact]
@@ -457,15 +480,13 @@ You can also use the PSSnapin property of the object that the Get-Command cmdlet
             Assert.Equal(5 + 3, examples.Length);
         }
 
-
         public static string[] GetXmlContent(string xml, string xpath)
         {
             List<string> result = new List<string>(); 
             XmlDocument xmlDoc = new XmlDocument();
             xmlDoc.LoadXml(xml);
             var nav = xmlDoc.CreateNavigator();
 
-
             XmlNamespaceManager xmlns = new XmlNamespaceManager(nav.NameTable);
             xmlns.AddNamespace("command", "http://schemas.microsoft.com/maml/dev/command/2004/10");
             xmlns.AddNamespace("maml", "http://schemas.microsoft.com/maml/2004/10");

test/Markdown.MAML.Test/Renderer/MamlRendererTests.cs

@@ -74,7 +74,6 @@ public void RendererProduceNameAndSynopsis()
             {
                     LinkName = "PowerShell made by Microsoft Hackathon",
                     LinkUri = "www.microsoft.com"
-                    
             }
             );
 
@@ -100,7 +99,7 @@ public void RendererProduceNameAndSynopsis()
             Assert.Equal(1, parameter2.Length);
             Assert.Equal("This is the path parameter description.", parameter2[0]);
 
-            string[] example1 = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:examples/command:example[maml:title='Example 1']/dev:code");
+            string[] example1 = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:examples/command:example[contains(maml:title,'Example 1')]/dev:code");
             Assert.Equal(1, example1.Length);
             Assert.Equal("PS:> Get-Help -YouNeedIt", example1[0]);
         }
@@ -167,9 +166,65 @@ public void RendererProduceEscapeXmlSpecialChars()
 
             string[] synopsis = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:details/maml:description/maml:para");
             Assert.Equal(1, synopsis.Length);
-            Assert.Equal(synopsis[0], command.Synopsis.Text);
+            Assert.Equal(command.Synopsis.Text, synopsis[0]);
         }
 
+        [Fact]
+        public void RendererProducePaddedExampleTitle()
+        {
+            MamlRenderer renderer = new MamlRenderer();
+            MamlCommand command = new MamlCommand()
+            {
+                Name = "Get-Foo",
+                Synopsis = new SectionBody("This is a description")
+            };
+
+            var example1 = new MamlExample()
+            {
+                Title = "Example 1",
+                Code = "PS:> Get-Help -YouNeedIt",
+                Remarks = "This does stuff!"
+            };
+
+            var example10 = new MamlExample()
+            {
+                Title = "Example 10",
+                Code = "PS:> Get-Help -YouNeedIt",
+                Remarks = "This does stuff!"
+            };
+
+            var exampleWithTitle = new MamlExample()
+            {
+                Title = "Example 11: With a title",
+                Code = "PS:> Get-Help -YouNeedIt",
+                Remarks = "This does stuff!"
+            };
+
+            var exampleWithLongTitle = new MamlExample()
+            {
+                Title = "Example 12: ".PadRight(66, 'A'),
+                Code = "PS:> Get-Help -YouNeedIt",
+                Remarks = "This does stuff!"
+            };
+
+            command.Examples.Add(example1);
+            command.Examples.Add(example10);
+            command.Examples.Add(exampleWithTitle);
+            command.Examples.Add(exampleWithLongTitle);
+
+            string maml = renderer.MamlModelToString(new[] { command });
+
+            // Check that example header is padded by dashes (-) unless to long
+            string[] example = EndToEndTests.GetXmlContent(maml, "/msh:helpItems/command:command/command:examples/command:example/maml:title");
+            Assert.Equal(4, example.Length);
+            Assert.Equal(63, example[0].Length);
+            Assert.Equal(64, example[1].Length);
+            Assert.Equal(66, example[3].Length);
+            Assert.Matches($"^-+ {example1.Title} -+$", example[0]);
+            Assert.Matches($"^-+ {example10.Title} -+$", example[1]);
+            Assert.Matches($"^-+ {exampleWithTitle.Title} -+$", example[2]);
+            Assert.Matches($"^{exampleWithLongTitle.Title}$", example[3]);
+        }
     }
 
 }

test/Markdown.MAML.Test/Renderer/MarkdownV2RendererTests.cs

@@ -126,7 +126,7 @@ public void RendererLineBreakAfterParameter()
         }
 
         [Fact]
-        public void RendererLineBreakAfterExample()
+        public void RendersExamplesFromMaml()
         {
             var renderer = new MarkdownV2Renderer(ParserMode.Full);
 
@@ -165,10 +165,34 @@ public void RendererLineBreakAfterExample()
                 Introduction = "Intro"
             };
 
+            var example5 = new MamlExample()
+            {
+                Title = "---Example 5---",
+                Code = "PS C:\\> Get-Help -Full",
+                Introduction = "With some dashes and no spaces"
+            };
+
+            var example6 = new MamlExample()
+            {
+                Title = "------------------ Example 6: With extra info ------------------",
+                Code = "PS C:\\> Get-Help -Full",
+                Introduction = "Padded to 64 characters and spaces"
+            };
+
+            var example7 = new MamlExample()
+            {
+                Title = "Example 7: ".PadRight(66, 'A'),
+                Code = "PS C:\\> Get-Help -Full",
+                Introduction = "Greater then 64 characters"
+            };
+
             command.Examples.Add(example1);
             command.Examples.Add(example2);
             command.Examples.Add(example3);
             command.Examples.Add(example4);
+            command.Examples.Add(example5);
+            command.Examples.Add(example6);
+            command.Examples.Add(example7);
 
             string markdown = renderer.MamlModelToString(command, null);
 
@@ -179,6 +203,11 @@ public void RendererLineBreakAfterExample()
             // Uses line break and should be preserved
             Assert.Contains("### Example 3\r\n\r\n```", markdown);
             Assert.Contains("### Example 4\r\n\r\nIntro\r\n\r\n```", markdown);
+
+            // Includes title padding that should be removed
+            Assert.Contains("### Example 5\r\n", markdown);
+            Assert.Contains("### Example 6: With extra info\r\n", markdown);
+            Assert.Contains($"### {example7.Title}\r\n", markdown);
         }
 
         [Fact]

test/Pester/FullLoop.Tests.ps1

@@ -73,9 +73,19 @@ Describe 'Full loop for Add-Member cmdlet' {
         # this '-' before force could be screwed up
         0..($generatedHelpObject.examples.example.Count - 1) | ForEach-Object {
             It ('generate correct example ' + ($generatedHelpObject.examples.example[$_].title)) -Skip:($_ -eq 5) {
-                ($generatedHelpObject.examples.example[$_] | Out-String).TrimEnd() | Should Be ($originalHelpObject.examples.example[$_] | Out-String).TrimEnd()
+                
+                $exampleExtractionRegex = '^(-| ){0,}(?<title>([^\f\n\r\t\v\x85\p{Z}-][^\f\n\r\t\v\x85]+[^\f\n\r\t\v\x85\p{Z}-]))(-| ){0,}(\r|\n){1,}(?<body>(\S|\s)+)';
+                $generatedMatches = [Regex]::Match(($generatedHelpObject.examples.example[$_] | Out-String).Trim(), $exampleExtractionRegex)
+                $originalMatches = [Regex]::Match(($originalHelpObject.examples.example[$_] | Out-String).Trim(), $exampleExtractionRegex)
+                
+                # Confirm match completed successfully
+                $generatedMatches.Success | Should Be $True
+                $originalMatches.Success | Should Be $True
+
+                # Match clean title and clean body seperately
+                $generatedMatches.Groups['title'].Value | Should Be $originalMatches.Groups['title'].Value
+                $generatedMatches.Groups['body'].Value | Should Be $originalMatches.Groups['body'].Value
             }
-            #($generatedHelpObject.examples | Out-String) | Should Be ($originalHelpObject.examples | Out-String)
         }
     }
 

test/Pester/PlatyPs.Tests.ps1

@@ -884,7 +884,7 @@ It has mutlilines. And hyper (http://link.com).
     It 'has a placeholder for example' {
         ($Help.examples.example | Measure-Object).Count | Should Be 1
         $e = $Help.examples.example
-        $e.Title | Should Be 'Example 1'
+        $e.Title | Should Match '-+ Example 1 -+'
         $e.Code | Should Match 'PS C:\>*'
     }