private static XElement CreateExample(MamlExample example)
{
return(new XElement(commandNS + "example",
new XElement(mamlNS + "title", example.Title),
new XElement(devNS + "code", example.Code),
new XElement(devNS + "remarks", GenerateParagraphs(example.Remarks))));
}
private static XElement CreateExample(MamlExample example)
{
return(new XElement(commandNS + "example",
new XElement(mamlNS + "title", PadExampleTitle(example.Title)),
new XElement(devNS + "code", string.Join("\r\n\r\n", example.Code.Select(block => block.Text))),
new XElement(devNS + "remarks", GenerateParagraphs(example.Remarks))));
}
protected MamlExample ExampleRule()
{
// grammar:
// #### ExampleTitle
// Introduction
// ```
// code
// ```
// Remarks
var node = GetNextNode();
var headingNode = GetHeadingWithExpectedLevel(node, EXAMPLE_HEADING_LEVEL);
if (headingNode == null)
{
return(null);
}
MamlExample example = new MamlExample()
{
Title = headingNode.Text
};
example.Introduction = GetTextFromParagraphNode(ParagraphNodeRule());
var codeBlock = CodeBlockRule();
example.Code = codeBlock.Text;
example.Remarks = GetTextFromParagraphNode(ParagraphNodeRule());
return(example);
}
private static YamlExample CreateExample(MamlExample mamlExample)
{
return(new YamlExample
{
Name = mamlExample.Title,
PreCode = mamlExample.Introduction,
Code = string.Join("\r\n\r\n", mamlExample.Code.Select(block => block.Text)),
PostCode = mamlExample.Remarks
});
}
private static YamlExample CreateExample(MamlExample mamlExample)
{
return(new YamlExample
{
Name = mamlExample.Title,
PreCode = mamlExample.Introduction,
Code = mamlExample.Code,
PostCode = mamlExample.Remarks
});
}
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 = new[] { new MamlCodeBlock("PS:> Get-Help -YouNeedIt") },
Remarks = "This does stuff!"
};
var example10 = new MamlExample()
{
Title = "Example 10",
Code = new[] { new MamlCodeBlock("PS:> Get-Help -YouNeedIt") },
Remarks = "This does stuff!"
};
var exampleWithTitle = new MamlExample()
{
Title = "Example 11: With a title",
Code = new[] { new MamlCodeBlock("PS:> Get-Help -YouNeedIt") },
Remarks = "This does stuff!"
};
var exampleWithLongTitle = new MamlExample()
{
Title = "Example 12: ".PadRight(66, 'A'),
Code = new[] { new MamlCodeBlock("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]);
}
protected MamlExample ExampleRule()
{
// grammar:
// #### ExampleTitle
// Introduction
// ```
// code
// ```
// Remarks
var node = GetNextNode();
try
{
var headingNode = GetHeadingWithExpectedLevel(node, EXAMPLE_HEADING_LEVEL);
if (headingNode == null)
{
return(null);
}
MamlExample example = new MamlExample()
{
Title = headingNode.Text
};
example.Introduction = GetTextFromParagraphNode(ParagraphNodeRule());
example.FormatOption = headingNode.FormatOption;
CodeBlockNode codeBlockNode;
List <MamlCodeBlock> codeBlocks = new List <MamlCodeBlock>();
while ((codeBlockNode = CodeBlockRule()) != null)
{
codeBlocks.Add(new MamlCodeBlock(
codeBlockNode.Text,
codeBlockNode.LanguageMoniker
));
}
example.Code = codeBlocks.ToArray();
example.Remarks = GetTextFromParagraphNode(ParagraphNodeRule());
return(example);
}
catch (HelpSchemaException headingException)
{
Report("Schema exception. This can occur when there are multiple code blocks in one example. " + headingException.Message);
throw headingException;
}
}
protected MamlExample ExampleRule()
{
// grammar:
// #### ExampleTitle
// Introduction
// ```
// code
// ```
// Remarks
var node = GetNextNode();
try
{
var headingNode = GetHeadingWithExpectedLevel(node, EXAMPLE_HEADING_LEVEL);
if (headingNode == null)
{
return(null);
}
MamlExample example = new MamlExample()
{
Title = headingNode.Text
};
example.Introduction = GetTextFromParagraphNode(ParagraphNodeRule());
CodeBlockNode codeBlock;
while ((codeBlock = CodeBlockRule()) != null)
{
if (example.Code == null)
{
example.Code = codeBlock.Text;
}
else
{
example.Code += "\r\n\r\n" + codeBlock.Text;
}
}
example.Remarks = GetTextFromParagraphNode(ParagraphNodeRule());
return(example);
}
catch (HelpSchemaException headingException)
{
Report("Schema exception. This can occur when there are multiple code blocks in one example. " + headingException.Message);
throw headingException;
}
}
public void RendersExamplesFromMaml()
{
var renderer = new MarkdownV2Renderer(ParserMode.Full);
MamlCommand command = new MamlCommand()
{
Name = "Test-LineBreak",
};
var example1 = new MamlExample()
{
Title = "Example 1",
Code = new[] { new MamlCodeBlock("PS C:\\> Get-Help") },
Remarks = "This is an example to get help."
};
var example2 = new MamlExample()
{
Title = "Example 2",
Code = new[] { new MamlCodeBlock("PS C:\\> Get-Help -Full") },
Introduction = "Intro"
};
var example3 = new MamlExample()
{
Title = "Example 3",
FormatOption = SectionFormatOption.LineBreakAfterHeader,
Code = new[] { new MamlCodeBlock("PS C:\\> Get-Help", "powershell") },
Remarks = "This is an example to get help."
};
var example4 = new MamlExample()
{
Title = "Example 4",
FormatOption = SectionFormatOption.LineBreakAfterHeader,
Code = new[] { new MamlCodeBlock("PS C:\\> Get-Help -Full") },
Introduction = "Intro"
};
var example5 = new MamlExample()
{
Title = "---Example 5---",
Code = new[] { new MamlCodeBlock("PS C:\\> Get-Help -Full") },
Introduction = "With some dashes and no spaces"
};
var example6 = new MamlExample()
{
Title = "------------------ Example 6: With extra info ------------------",
Code = new[] { new MamlCodeBlock("PS C:\\> Get-Help -Full") },
Introduction = "Padded to 64 characters and spaces"
};
var example7 = new MamlExample()
{
Title = "Example 7: ".PadRight(66, 'A'),
Code = new[] { new MamlCodeBlock("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);
// Does not use line break and should not be added
Assert.Contains("### Example 1\r\n```", markdown);
Assert.Contains("### Example 2\r\nIntro\r\n\r\n```", markdown);
// Uses line break and should be preserved
Assert.Contains("### Example 3\r\n\r\n```powershell", 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);
}
