Updated maml generation to pad example header PowerShell#119

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);
         }
 

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/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:\>*'
     }