diff --git a/docs/Get-HelpPreview.md b/docs/Get-HelpPreview.md index 651db8f1..27fb0f7d 100644 --- a/docs/Get-HelpPreview.md +++ b/docs/Get-HelpPreview.md @@ -106,6 +106,3 @@ You can pipe an array of paths to this cmdlet. ### Help Object This cmdlet returns a **Help** object, which is the same output as **Get-Help**. -## NOTES - -## RELATED LINKS diff --git a/docs/Get-MarkdownMetadata.md b/docs/Get-MarkdownMetadata.md index dad4e873..d1e56d1d 100644 --- a/docs/Get-MarkdownMetadata.md +++ b/docs/Get-MarkdownMetadata.md @@ -133,6 +133,3 @@ You can pipe an array of paths to this cmdlet. The cmdlet returns a **Dictionary\[String, String\]** object. The dictionary contains key-value pairs found in the markdown metadata block. -## NOTES - -## RELATED LINKS diff --git a/docs/Merge-MarkdownHelp.md b/docs/Merge-MarkdownHelp.md index dbb8e8cc..0773894a 100644 --- a/docs/Merge-MarkdownHelp.md +++ b/docs/Merge-MarkdownHelp.md @@ -14,7 +14,7 @@ Merge multiple markdown versions of the same cmdlet into a single markdown file. ``` Merge-MarkdownHelp [-Path] [-OutputPath] [-Encoding ] [-ExplicitApplicableIfAll] - [-Force] [[-MergeMarker] ] [] + [-Force] [-NoInputOutputFormatting] [[-MergeMarker] ] [] ``` ## DESCRIPTION @@ -141,6 +141,21 @@ Accept pipeline input: True (ByValue) Accept wildcard characters: True ``` +### -NoInputOutputFormatting +Will prevent Input/Output comments from being formatted. This might be needed because Microsoft gives us no way to actually set the values in Input/Output correct (type, description) in a PS function header, but will put everything written down there into the "type" property, so all text would be formatted bold in that case. For the Input/Output texts in a PS function header to be written without bold formatting (as is) this switch needs to be provided. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). @@ -152,6 +167,3 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.IO.FileInfo[] -## NOTES - -## RELATED LINKS diff --git a/docs/New-ExternalHelp.md b/docs/New-ExternalHelp.md index 1490e13c..b55de047 100644 --- a/docs/New-ExternalHelp.md +++ b/docs/New-ExternalHelp.md @@ -232,8 +232,6 @@ You can pipe an array of paths to this cmdlet. ### System.IO.FileInfo[] This cmdlet returns a **FileInfo[]** object for created files. -## NOTES - ## RELATED LINKS [PowerShell V2 External MAML Help](https://blogs.msdn.microsoft.com/powershell/2008/12/24/powershell-v2-external-maml-help/) diff --git a/docs/New-ExternalHelpCab.md b/docs/New-ExternalHelpCab.md index 44227732..57f0198b 100644 --- a/docs/New-ExternalHelpCab.md +++ b/docs/New-ExternalHelpCab.md @@ -118,8 +118,6 @@ You cannot pipe values to this cmdlet. This cmdlet does not generate output. The cmldet saves its results in the output folder that the *OutputPath* parameter specifies. -## NOTES - ## RELATED LINKS [New-ExternalHelp](New-ExternalHelp.md) diff --git a/docs/New-MarkdownHelp.md b/docs/New-MarkdownHelp.md index e83e3275..4dd5c931 100644 --- a/docs/New-MarkdownHelp.md +++ b/docs/New-MarkdownHelp.md @@ -16,23 +16,27 @@ Creates help in markdown format. ``` New-MarkdownHelp -Module [-Session ] [-Force] [-AlphabeticParamsOrder] [-Metadata ] -OutputFolder [-NoMetadata] [-UseFullTypeName] [-Encoding ] - [-WithModulePage] [-ModulePagePath ] [-Locale ] [-HelpVersion ] [-FwLink ] - [-ExcludeDontShow] [] + [-SinglePage] [-WithModulePage] [-ModulePagePath ] [-Locale ] [-HelpVersion ] + [-FwLink ] [-ExcludeDontShow] [-NoInputOutputFormatting] [-SkipEmptyFields] [-CreateTableOfContent] + [-WithModuleMetaData] [] ``` ### FromCommand ``` New-MarkdownHelp -Command [-Session ] [-Force] [-AlphabeticParamsOrder] [-Metadata ] [-OnlineVersionUrl ] -OutputFolder [-NoMetadata] [-UseFullTypeName] - [-Encoding ] [-ExcludeDontShow] [] + [-Encoding ] [-ExcludeDontShow] [-NoInputOutputFormatting] [-SkipEmptyFields] + [-CreateTableOfContent] [-WithModuleMetaData] [] ``` ### FromMaml ``` New-MarkdownHelp -MamlFile [-ConvertNotesToList] [-ConvertDoubleDashLists] [-Force] [-AlphabeticParamsOrder] [-Metadata ] -OutputFolder [-NoMetadata] [-UseFullTypeName] - [-Encoding ] [-WithModulePage] [-ModulePagePath ] [-Locale ] [-HelpVersion ] - [-FwLink ] [-ModuleName ] [-ModuleGuid ] [-ExcludeDontShow] [] + [-Encoding ] [-SinglePage] [-WithModulePage] [-ModulePagePath ] [-Locale ] + [-HelpVersion ] [-FwLink ] [-ModuleName ] [-ModuleGuid ] [-ExcludeDontShow] + [-NoInputOutputFormatting] [-SkipEmptyFields] [-CreateTableOfContent] [-WithModuleMetaData] + [] ``` ## DESCRIPTION @@ -490,6 +494,81 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -CreateTableOfContent +Will create an additional table of content in the single- or module-landing-page. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoInputOutputFormatting +Will prevent Input/Output comments from being formatted. This might be needed because Microsoft gives us no way to actually set the values in Input/Output correct (type, description) in a PS function header, but will put everything written down there into the "type" property, so all text would be formatted bold in that case. For the Input/Output texts in a PS function header to be written without bold formatting (as is) this switch needs to be provided. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SinglePage +Will create a single markdown file with the description of the module and each cmdlet/function, instead of writing a new markdown file for each cmdlet/function. + +```yaml +Type: SwitchParameter +Parameter Sets: FromModule, FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipEmptyFields +Will omit example texts for empty fields which were not provided/found in the documentation and will instead just skip empty sections (example: no "Notes" section if no "Notes" were provided). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WithModuleMetaData +Will add a section "Module Metadata" filled with the following data (as far as that data exists): Module version, Module GUID, Author, Company, Copyright, Tags, License Uri, Project Uri. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). @@ -504,8 +583,6 @@ These are the modules from which this cmdlet creates help markdown. ### System.IO.FileInfo[] This cmdlet returns a **FileInfo[]** object for created files. -## NOTES - ## RELATED LINKS [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) diff --git a/docs/New-YamlHelp.md b/docs/New-YamlHelp.md index 019e300f..7f4c3b47 100644 --- a/docs/New-YamlHelp.md +++ b/docs/New-YamlHelp.md @@ -148,6 +148,3 @@ You can pipe an array of paths to this cmdlet. ### System.IO.FileInfo[] This cmdlet returns a **FileInfo[]** object for created files. -## NOTES - -## RELATED LINKS diff --git a/docs/Update-MarkdownHelp.md b/docs/Update-MarkdownHelp.md index ea3b755f..59803c53 100644 --- a/docs/Update-MarkdownHelp.md +++ b/docs/Update-MarkdownHelp.md @@ -15,7 +15,7 @@ Update PlatyPS markdown help files. ``` Update-MarkdownHelp [-Path] [[-Encoding] ] [[-LogPath] ] [-LogAppend] [-AlphabeticParamsOrder] [-UseFullTypeName] [-UpdateInputOutput] [-Force] [-Session ] - [-ExcludeDontShow] [] + [-ExcludeDontShow] [-NoInputOutputFormatting] [-SkipEmptyFields] [] ``` ## DESCRIPTION @@ -232,6 +232,36 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -NoInputOutputFormatting +Will prevent Input/Output comments from being formatted. This might be needed because Microsoft gives us no way to actually set the values in Input/Output correct (type, description) in a PS function header, but will put everything written down there into the "type" property, so all text would be formatted bold in that case. For the Input/Output texts in a PS function header to be written without bold formatting (as is) this switch needs to be provided. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipEmptyFields +Will omit example texts for empty fields which were not provided/found in the documentation and will instead just skip empty sections (example: no "Notes" section if no "Notes" were provided). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). diff --git a/docs/Update-MarkdownHelpModule.md b/docs/Update-MarkdownHelpModule.md index 02791a27..50a1d6ca 100644 --- a/docs/Update-MarkdownHelpModule.md +++ b/docs/Update-MarkdownHelpModule.md @@ -15,7 +15,8 @@ Update all files in a markdown help module folder. ``` Update-MarkdownHelpModule [-Path] [[-Encoding] ] [-RefreshModulePage] [-ModulePagePath ] [[-LogPath] ] [-LogAppend] [-AlphabeticParamsOrder] [-UseFullTypeName] - [-UpdateInputOutput] [-Force] [-Session ] [-ExcludeDontShow] [] + [-UpdateInputOutput] [-Force] [-Session ] [-ExcludeDontShow] [-SkipEmptyFields] + [] ``` ## DESCRIPTION @@ -239,6 +240,21 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -SkipEmptyFields +Will omit example texts for empty fields which were not provided/found in the documentation and will instead just skip empty sections (example: no "Notes" section if no "Notes" were provided). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). diff --git a/src/Markdown.MAML/Renderer/Markdownv2Renderer.cs b/src/Markdown.MAML/Renderer/Markdownv2Renderer.cs index 32c7ddb9..570b6690 100644 --- a/src/Markdown.MAML/Renderer/Markdownv2Renderer.cs +++ b/src/Markdown.MAML/Renderer/Markdownv2Renderer.cs @@ -41,7 +41,7 @@ public MarkdownV2Renderer(ParserMode mode, int maxSyntaxWidth) public string MamlModelToString(MamlCommand mamlCommand, bool skipYamlHeader) { - return MamlModelToString(mamlCommand, null, skipYamlHeader); + return MamlModelToString(mamlCommand, skipYamlHeader, false); } public string MamlModelToString(MamlCommand mamlCommand, Hashtable yamlHeader) @@ -49,7 +49,37 @@ public string MamlModelToString(MamlCommand mamlCommand, Hashtable yamlHeader) return MamlModelToString(mamlCommand, yamlHeader, false); } - private string MamlModelToString(MamlCommand mamlCommand, Hashtable yamlHeader, bool skipYamlHeader) + public string MamlModelToString(int levelRoot, MamlCommand mamlCommand, bool skipYamlHeader) + { + return MamlModelToString(levelRoot, mamlCommand, skipYamlHeader, false); + } + + public string MamlModelToString(int levelRoot, MamlCommand mamlCommand, Hashtable yamlHeader) + { + return MamlModelToString(levelRoot, mamlCommand, yamlHeader, false); + } + + public string MamlModelToString(MamlCommand mamlCommand, bool skipYamlHeader, bool noFormatForInputOutput) + { + return MamlModelToString(0, mamlCommand, null, skipYamlHeader, noFormatForInputOutput); + } + + public string MamlModelToString(MamlCommand mamlCommand, Hashtable yamlHeader, bool noFormatForInputOutput) + { + return MamlModelToString(0, mamlCommand, yamlHeader, false, noFormatForInputOutput); + } + + public string MamlModelToString(int levelRoot, MamlCommand mamlCommand, bool skipYamlHeader, bool noFormatForInputOutput) + { + return MamlModelToString(levelRoot, mamlCommand, null, skipYamlHeader, noFormatForInputOutput); + } + + public string MamlModelToString(int levelRoot, MamlCommand mamlCommand, Hashtable yamlHeader, bool noFormatForInputOutput) + { + return MamlModelToString(levelRoot, mamlCommand, yamlHeader, false, noFormatForInputOutput); + } + + private string MamlModelToString(int levelRoot, MamlCommand mamlCommand, Hashtable yamlHeader, bool skipYamlHeader, bool noFormatForInputOutput) { // clear, so we can re-use this instance _stringBuilder.Clear(); @@ -65,7 +95,7 @@ private string MamlModelToString(MamlCommand mamlCommand, Hashtable yamlHeader, AddYamlHeader(yamlHeader); } - AddCommand(mamlCommand); + AddCommand(levelRoot, mamlCommand, noFormatForInputOutput); // at the end, just normalize all ends return RenderCleaner.NormalizeLineBreaks( @@ -93,46 +123,47 @@ private void AddYamlHeader(Hashtable yamlHeader) _stringBuilder.AppendFormat("---{0}{0}", NewLine); } - private void AddCommand(MamlCommand command) + private void AddCommand(int levelRoot, MamlCommand command, bool noFormatForInputOutput) { - AddHeader(ModelTransformerBase.COMMAND_NAME_HEADING_LEVEL, command.Name); - AddEntryHeaderWithText(MarkdownStrings.SYNOPSIS, command.Synopsis); - AddSyntax(command); - AddEntryHeaderWithText(MarkdownStrings.DESCRIPTION, command.Description); - AddExamples(command); - AddParameters(command); - AddInputs(command); - AddOutputs(command); - AddEntryHeaderWithText(MarkdownStrings.NOTES, command.Notes); - AddLinks(command); + AddHeader(levelRoot, ModelTransformerBase.COMMAND_NAME_HEADING_LEVEL, command.Name); + AddEntryHeaderWithText(levelRoot, MarkdownStrings.SYNOPSIS, command.Synopsis); + AddSyntax(levelRoot, command); + AddEntryHeaderWithText(levelRoot, MarkdownStrings.DESCRIPTION, command.Description); + AddExamples(levelRoot, command); + AddParameters(levelRoot, command); + AddInputs(levelRoot, command, noFormatForInputOutput); + AddOutputs(levelRoot, command, noFormatForInputOutput); + AddEntryHeaderWithText(levelRoot, MarkdownStrings.NOTES, command.Notes); + AddLinks(levelRoot, command); } - private void AddLinks(MamlCommand command) + private void AddLinks(int levelRoot, MamlCommand command) { - var extraNewLine = command.Links != null && command.Links.Count > 0; - - AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.RELATED_LINKS, extraNewLine); - foreach (var link in command.Links) + if (command.Links != null && command.Links.Count > 0) { - if (link.IsSimplifiedTextLink) + AddHeader(levelRoot, ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.RELATED_LINKS, extraNewLine: true); + foreach (var link in command.Links) { - _stringBuilder.AppendFormat("{0}", link.LinkName); - } - else - { - var name = link.LinkName; - if (string.IsNullOrEmpty(name)) + if (link.IsSimplifiedTextLink) { - // we need a valid name to produce a valid markdown - name = link.LinkUri; + _stringBuilder.AppendFormat("{0}", link.LinkName); } + else + { + var name = link.LinkName; + if (string.IsNullOrEmpty(name)) + { + // we need a valid name to produce a valid markdown + name = link.LinkUri; + } - _stringBuilder.AppendFormat("[{0}]({1}){2}{2}", name, link.LinkUri, NewLine); + _stringBuilder.AppendFormat("[{0}]({1}){2}{2}", name, link.LinkUri, NewLine); + } } } } - private void AddInputOutput(MamlInputOutput io) + private void AddInputOutput(int levelRoot, MamlInputOutput io, bool noFormatForInputOutput) { if (string.IsNullOrEmpty(io.TypeName) && string.IsNullOrEmpty(io.Description)) { @@ -141,57 +172,80 @@ private void AddInputOutput(MamlInputOutput io) } var extraNewLine = ShouldBreak(io.FormatOption); - AddHeader(ModelTransformerBase.INPUT_OUTPUT_TYPENAME_HEADING_LEVEL, io.TypeName, extraNewLine); - AddParagraphs(io.Description); + if(noFormatForInputOutput) + { + if(!string.IsNullOrWhiteSpace(io.TypeName)) + { + AddParagraphs(io.TypeName, false, true); + } + if (!string.IsNullOrWhiteSpace(io.Description)) + { + AddParagraphs(io.Description, false, true); + } + } + else + { + AddHeader(levelRoot, ModelTransformerBase.INPUT_OUTPUT_TYPENAME_HEADING_LEVEL, io.TypeName, extraNewLine); + AddParagraphs(io.Description); + } } - private void AddOutputs(MamlCommand command) + private void AddOutputs(int levelRoot, MamlCommand command, bool noFormatForInputOutput) { - AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.OUTPUTS); - foreach (var io in command.Outputs) + if(command.Outputs != null && command.Outputs.Count(itm => !string.IsNullOrEmpty(itm.TypeName) || !string.IsNullOrEmpty(itm.Description)) > 0) { - AddInputOutput(io); + AddHeader(levelRoot, ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.OUTPUTS); + foreach (var io in command.Outputs) + { + AddInputOutput(levelRoot, io, noFormatForInputOutput); + } } } - private void AddInputs(MamlCommand command) + private void AddInputs(int levelRoot, MamlCommand command, bool noFormatForInputOutput) { - AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.INPUTS); - foreach (var io in command.Inputs) + if (command.Inputs != null && command.Inputs.Count(itm => !string.IsNullOrEmpty(itm.TypeName) || !string.IsNullOrEmpty(itm.Description)) > 0) { - AddInputOutput(io); + AddHeader(levelRoot, ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.INPUTS); + foreach (var io in command.Inputs) + { + AddInputOutput(levelRoot, io, noFormatForInputOutput); + } } } - private void AddParameters(MamlCommand command) + private void AddParameters(int levelRoot, MamlCommand command) { - AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.PARAMETERS); - foreach (var param in command.Parameters) + if((command.Parameters != null && command.Parameters.Count > 0) || command.SupportCommonParameters || command.IsWorkflow) { - AddParameter(param, command); - } + AddHeader(levelRoot, ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.PARAMETERS); + foreach (var param in command.Parameters) + { + AddParameter(levelRoot, param, command); + } - if (command.IsWorkflow) - { - AddWorkflowParameters(); - } + if (command.IsWorkflow) + { + AddWorkflowParameters(levelRoot); + } - // Workflows always support CommonParameters - if (command.SupportCommonParameters || command.IsWorkflow) - { - AddCommonParameters(); + // Workflows always support CommonParameters + if (command.SupportCommonParameters || command.IsWorkflow) + { + AddCommonParameters(levelRoot); + } } } - private void AddCommonParameters() + private void AddCommonParameters(int levelRoot) { - AddHeader(ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, MarkdownStrings.CommonParametersToken, extraNewLine: false); + AddHeader(levelRoot, ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, MarkdownStrings.CommonParametersToken, extraNewLine: false); AddParagraphs(MarkdownStrings.CommonParametersText, noNewLines: false, skipAutoWrap: true); } - private void AddWorkflowParameters() + private void AddWorkflowParameters(int levelRoot) { - AddHeader(ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, MarkdownStrings.WorkflowParametersToken, extraNewLine: false); + AddHeader(levelRoot, ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, MarkdownStrings.WorkflowParametersToken, extraNewLine: false); AddParagraphs(MarkdownStrings.WorkflowParametersText, noNewLines: false, skipAutoWrap: true); } @@ -268,11 +322,11 @@ private bool ShouldBreak(SectionFormatOption formatOption) return formatOption.HasFlag(SectionFormatOption.LineBreakAfterHeader); } - private void AddParameter(MamlParameter parameter, MamlCommand command) + private void AddParameter(int levelRoot, MamlParameter parameter, MamlCommand command) { var extraNewLine = ShouldBreak(parameter.FormatOption); - AddHeader(ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, '-' + parameter.Name, extraNewLine: extraNewLine); + AddHeader(levelRoot, ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, '-' + parameter.Name, extraNewLine: extraNewLine); AddParagraphs(parameter.Description); @@ -332,31 +386,34 @@ private void AppendYamlKeyValue(string key, string value) _stringBuilder.AppendFormat("{0}: {1}{2}", key, value, NewLine); } - private void AddExamples(MamlCommand command) + private void AddExamples(int levelRoot, MamlCommand command) { - AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.EXAMPLES); - foreach (var example in command.Examples) + if(command.Examples != null && command.Examples.Count > 0) { - var extraNewLine = ShouldBreak(example.FormatOption); + AddHeader(levelRoot, ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.EXAMPLES); + foreach (var example in command.Examples) + { + var extraNewLine = ShouldBreak(example.FormatOption); - AddHeader(ModelTransformerBase.EXAMPLE_HEADING_LEVEL, GetExampleTitle(example.Title), extraNewLine: extraNewLine); + AddHeader(levelRoot, ModelTransformerBase.EXAMPLE_HEADING_LEVEL, GetExampleTitle(example.Title), extraNewLine: extraNewLine); - if (!string.IsNullOrEmpty(example.Introduction)) - { - AddParagraphs(example.Introduction); - } + if (!string.IsNullOrEmpty(example.Introduction)) + { + AddParagraphs(example.Introduction); + } - if (example.Code != null) - { - for (var i = 0; i < example.Code.Length; i++) + if (example.Code != null) { - AddCodeSnippet(example.Code[i].Text, example.Code[i].LanguageMoniker); + for (var i = 0; i < example.Code.Length; i++) + { + AddCodeSnippet(example.Code[i].Text, example.Code[i].LanguageMoniker); + } } - } - if (!string.IsNullOrEmpty(example.Remarks)) - { - AddParagraphs(example.Remarks); + if (!string.IsNullOrEmpty(example.Remarks)) + { + AddParagraphs(example.Remarks); + } } } } @@ -440,30 +497,34 @@ public static string GetSyntaxString(MamlCommand command, MamlSyntax syntax, int return sb.ToString(); } - private void AddSyntax(MamlCommand command) + private void AddSyntax(int levelRoot, MamlCommand command) { - AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.SYNTAX); - foreach (var syntax in command.Syntax) + if(command.Syntax != null && command.Syntax.Count > 0) { - if (command.Syntax.Count > 1) + AddHeader(levelRoot, ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.SYNTAX); + foreach (var syntax in command.Syntax) { - AddHeader(ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, string.Format("{0}{1}",syntax.ParameterSetName,syntax.IsDefault ? MarkdownStrings.DefaultParameterSetModifier : null), extraNewLine: false); + if (command.Syntax.Count > 1) + { + AddHeader(levelRoot, ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, string.Format("{0}{1}", syntax.ParameterSetName, syntax.IsDefault ? MarkdownStrings.DefaultParameterSetModifier : null), extraNewLine: false); + } + + AddCodeSnippet(GetSyntaxString(command, syntax)); } - AddCodeSnippet(GetSyntaxString(command, syntax)); } } - private void AddEntryHeaderWithText(string header, SectionBody body) + private void AddEntryHeaderWithText(int levelRoot, string header, SectionBody body) { - var extraNewLine = body == null || string.IsNullOrEmpty(body.Text) || ShouldBreak(body.FormatOption); - - // Add header - AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, header, extraNewLine: extraNewLine); - // to correctly handle empty text case, we are adding new-line here if (body != null && !string.IsNullOrEmpty(body.Text)) { + var extraNewLine = body == null || string.IsNullOrEmpty(body.Text) || ShouldBreak(body.FormatOption); + + // Add header + AddHeader(levelRoot, ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, header, extraNewLine: extraNewLine); + AddParagraphs(body.Text); } } @@ -473,9 +534,9 @@ private void AddCodeSnippet(string code, string lang = "") _stringBuilder.AppendFormat("```{1}{2}{0}{2}```{2}{2}", code, lang, NewLine); } - private void AddHeader(int level, string header, bool extraNewLine = true) + private void AddHeader(int levelRoot, int levelLocal, string header, bool extraNewLine = true) { - for (int i = 0; i < level; i++) + for (int i = 0; i < levelRoot + levelLocal; i++) { _stringBuilder.Append('#'); } diff --git a/src/Markdown.MAML/Renderer/YamlRenderer.cs b/src/Markdown.MAML/Renderer/YamlRenderer.cs index f85000ab..20897a27 100644 --- a/src/Markdown.MAML/Renderer/YamlRenderer.cs +++ b/src/Markdown.MAML/Renderer/YamlRenderer.cs @@ -18,9 +18,9 @@ public static string MamlModelToString(MamlCommand mamlCommand) var model = new YamlCommand { Name = mamlCommand.Name, - Notes = mamlCommand.Notes.Text, - Remarks = mamlCommand.Description.Text, - Summary = mamlCommand.Synopsis.Text, + Notes = mamlCommand.Notes?.Text, + Remarks = mamlCommand.Description?.Text, + Summary = mamlCommand.Synopsis?.Text, Examples = mamlCommand.Examples.Select(CreateExample).ToList(), Inputs = mamlCommand.Inputs.Select(CreateInputOutput).ToList(), Links = mamlCommand.Links.Select(CreateLink).ToList(), diff --git a/src/platyPS/platyPS.psd1 b/src/platyPS/platyPS.psd1 index bbd8963b..3e3b4758 100644 --- a/src/platyPS/platyPS.psd1 +++ b/src/platyPS/platyPS.psd1 @@ -77,7 +77,8 @@ FunctionsToExport = @( 'Update-MarkdownHelp', 'Update-MarkdownHelpModule', 'New-MarkdownAboutHelp', - 'Merge-MarkdownHelp' + 'Merge-MarkdownHelp', + 'GetMamlObject' ) # Cmdlets to export from this module diff --git a/src/platyPS/platyPS.psm1 b/src/platyPS/platyPS.psm1 index 763023db..a0d35a77 100644 --- a/src/platyPS/platyPS.psm1 +++ b/src/platyPS/platyPS.psm1 @@ -37,6 +37,9 @@ $script:MODULE_PAGE_FW_LINK = "Download Help Link" $script:MODULE_PAGE_HELP_VERSION = "Help Version" $script:MODULE_PAGE_ADDITIONAL_LOCALE = "Additional Locale" +$script:MAML_DATA_CONTENT = "Maml Content" +$script:MAML_DATA_COMMAND_NAME = "Command Name" + $script:MAML_ONLINE_LINK_DEFAULT_MONIKER = 'Online Version:' function New-MarkdownHelp @@ -85,6 +88,10 @@ function New-MarkdownHelp [System.Text.Encoding]$Encoding = $script:UTF8_NO_BOM, + [Parameter(ParameterSetName="FromModule")] + [Parameter(ParameterSetName="FromMaml")] + [switch]$SinglePage, + [Parameter(ParameterSetName="FromModule")] [Parameter(ParameterSetName="FromMaml")] [switch]$WithModulePage, @@ -101,12 +108,12 @@ function New-MarkdownHelp [Parameter(ParameterSetName="FromModule")] [Parameter(ParameterSetName="FromMaml")] [string] - $HelpVersion = $LocalizedData.HelpVersion, + $HelpVersion = $null, [Parameter(ParameterSetName="FromModule")] [Parameter(ParameterSetName="FromMaml")] [string] - $FwLink = $LocalizedData.FwLink, + $FwLink = $null, [Parameter(ParameterSetName="FromMaml")] [string] @@ -117,13 +124,53 @@ function New-MarkdownHelp $ModuleGuid = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", [switch] - $ExcludeDontShow + $ExcludeDontShow, + + [switch] + $NoInputOutputFormatting, + + [switch] + $SkipEmptyFields, + + [switch] + $CreateTableOfContent, + + [switch] + $WithModuleMetaData ) begin { validateWorkingProvider New-Item -Type Directory $OutputFolder -ErrorAction SilentlyContinue > $null + + if(!$SkipEmptyFields.IsPresent) { + if([string]::IsNullOrWhiteSpace($HelpVersion)) { + $HelpVersion = $LocalizedData.HelpVersion + } + if([string]::IsNullOrWhiteSpace($FwLink)) { + $FwLink = $LocalizedData.FwLink + } + } + + if($WithModuleMetaData.IsPresent) { + $ModuleMetaData = [PSCustomObject]@{ + ModuleVersion = $null + GUID = $null + Author = $null + CompanyName = $null + Copyright = $null + ReleaseNotes = $null + Tags = @() + LicenseUri = $null + ProjectUri = $null + RequiredModules = @() + RequiredAssemblies = @() + } + } + else { + $ModuleMetaData = $null + } } process @@ -140,7 +187,7 @@ function New-MarkdownHelp # # Example - if ($MamlCommandObject.Examples.Count -eq 0) + if (!$SkipEmptyFields.IsPresent -and $MamlCommandObject.Examples.Count -eq 0) { $MamlExampleObject = New-Object -TypeName Markdown.MAML.Model.MAML.MamlExample @@ -159,12 +206,13 @@ function New-MarkdownHelp } } - function processMamlObjectToFile + function processMamlObject { param( [Parameter(ValueFromPipeline=$true)] [ValidateNotNullOrEmpty()] - [Markdown.MAML.Model.MAML.MamlCommand]$mamlObject + [Markdown.MAML.Model.MAML.MamlCommand]$mamlObject, + [int]$rootLevel = 0 ) process @@ -235,12 +283,32 @@ function New-MarkdownHelp $script:EXTERNAL_HELP_FILE_YAML_HEADER = $helpFileName $script:ONLINE_VERSION_YAML_HEADER = $online $script:MODULE_PAGE_MODULE_NAME = $mamlObject.ModuleName + }) } - $md = ConvertMamlModelToMarkdown -mamlCommand $mamlObject -metadata $newMetadata -NoMetadata:$NoMetadata + return @{ + $script:MAML_DATA_CONTENT = (ConvertMamlModelToMarkdown -mamlCommand $mamlObject -metadata $newMetadata -rootLevel $rootLevel -NoMetadata:$NoMetadata -NoInputOutputFormatting:$NoInputOutputFormatting) + $script:MAML_DATA_COMMAND_NAME = $commandName + } + } + } + + function processMamlObjectToFile + { + param( + [Parameter(ValueFromPipeline=$true)] + [ValidateNotNullOrEmpty()] + [Markdown.MAML.Model.MAML.MamlCommand]$mamlObject + ) + + process + { + $md = processMamlObject -mamlObject $mamlObject + + $commandName = $md[$script:MAML_DATA_COMMAND_NAME] - MySetContent -path (Join-Path $OutputFolder "$commandName.md") -value $md -Encoding $Encoding -Force:$Force + MySetContent -path (Join-Path $OutputFolder "$commandName.md") -value $md[$script:MAML_DATA_CONTENT] -Encoding $Encoding -Force:$Force } } @@ -257,7 +325,7 @@ function New-MarkdownHelp throw $LocalizedData.CommandNotFound -f $_ } - GetMamlObject -Session $Session -Cmdlet $_ -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow.IsPresent | processMamlObjectToFile + GetMamlObject -Session $Session -Cmdlet $_ -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields | processMamlObjectToFile } } else @@ -272,33 +340,83 @@ function New-MarkdownHelp } $iterator | ForEach-Object { - if ($PSCmdlet.ParameterSetName -eq 'FromModule') - { - if (-not (GetCommands -AsNames -module $_)) + $ModuleName = $null + $ModuleGuid = $null + $ModuleDescription = $null + $ModuleVersion = $null + + if($SinglePage.IsPresent) { + $MamlContents = @() + + if ($PSCmdlet.ParameterSetName -eq 'FromModule') { - throw $LocalizedData.ModuleNotFound -f $_ + if (-not (GetCommands -AsNames -module $_)) + { + throw $LocalizedData.ModuleNotFound -f $_ + } + + $MamlContents = @(GetMamlObject -Session $Session -Module $_ -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields | processMamlObject -rootLevel 2 | ForEach-Object { return $_[$script:MAML_DATA_CONTENT] }) + + $ModuleName = $_ + $ModObj = (Get-Module $ModuleName) + if($null -ne $ModObj) { + $ModuleGuid = $ModObj.Guid + $ModuleDescription = $ModObj.Description + if($null -ne $ModObj.Version) { + $ModuleVersion = $ModObj.Version.ToString() + } + if($null -ne $ModuleMetaData) { + + $ModuleMetaData.ModuleVersion = $ModuleVersion + $MetaDataGuid = $ModuleGuid.ToString() + if(![string]::IsNullOrWhiteSpace($MetaDataGuid)) { + $ModuleMetaData.GUID = $MetaDataGuid + } + if(![string]::IsNullOrWhiteSpace($ModObj.Author)) { + $ModuleMetaData.Author = $ModObj.Author + } + if(![string]::IsNullOrWhiteSpace($ModObj.CompanyName)) { + $ModuleMetaData.CompanyName = $ModObj.CompanyName + } + if(![string]::IsNullOrWhiteSpace($ModObj.Copyright)) { + $ModuleMetaData.Copyright = $ModObj.Copyright + } + if(![string]::IsNullOrWhiteSpace($ModObj.ReleaseNotes)) { + $ModuleMetaData.ReleaseNotes = $ModObj.ReleaseNotes + } + if($null -ne $ModObj.Tags) { + $FilteredTags = @($ModObj.Tags | Where-Object { ![string]::IsNullOrWhiteSpace($_) } | Sort-Object -Unique) + if($FilteredTags.Count -gt 0) { + $ModuleMetaData.Tags = @($FilteredTags) + } + } + if($null -ne $ModObj.LicenseUri -and ![string]::IsNullOrWhiteSpace($ModObj.LicenseUri.OriginalString)) { + $ModuleMetaData.LicenseUri = $ModObj.LicenseUri.OriginalString.Trim() + } + if($null -ne $ModObj.ProjectUri -and ![string]::IsNullOrWhiteSpace($ModObj.ProjectUri.OriginalString)) { + $ModuleMetaData.ProjectUri = $ModObj.ProjectUri.OriginalString.Trim() + } + $ModuleMetaData.RequiredModules = @($ModObj.RequiredModules) + $ModuleMetaData.RequiredAssemblies = @($ModObj.RequiredAssemblies) + } + } + $CmdletNames = GetCommands -AsNames -Module $ModuleName } - - GetMamlObject -Session $Session -Module $_ -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow.IsPresent | processMamlObjectToFile - - $ModuleName = $_ - $ModuleGuid = (Get-Module $ModuleName).Guid - $CmdletNames = GetCommands -AsNames -Module $ModuleName - } - else # 'FromMaml' - { - if (-not (Test-Path $_)) + else # 'FromMaml' { - throw $LocalizedData.FileNotFound -f $_ - } - - GetMamlObject -MamlFile $_ -ConvertNotesToList:$ConvertNotesToList -ConvertDoubleDashLists:$ConvertDoubleDashLists -ExcludeDontShow:$ExcludeDontShow.IsPresent | processMamlObjectToFile + # Set ModuleName to MamlModule (since it's set to null at the beginning now) + $ModuleName = "MamlModule" - $CmdletNames += GetMamlObject -MamlFile $_ -ExcludeDontShow:$ExcludeDontShow.IsPresent | ForEach-Object {$_.Name} - } + if (-not (Test-Path $_)) + { + throw $LocalizedData.FileNotFound -f $_ + } + + $MamlContents = @(GetMamlObject -MamlFile $_ -ConvertNotesToList:$ConvertNotesToList -ConvertDoubleDashLists:$ConvertDoubleDashLists -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields | processMamlObject -rootLevel 2 | Select-Object -ExpandProperty $script:MAML_DATA_CONTENT) + + $CmdletNames += GetMamlObject -MamlFile $_ -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields | ForEach-Object {$_.Name} + } - if($WithModulePage) - { if(-not $ModuleGuid) { $ModuleGuid = "00000000-0000-0000-0000-000000000000" @@ -307,17 +425,121 @@ function New-MarkdownHelp { Write-Warning -Message $LocalizedData.MoreThanOneGuid } + # yeild - NewModuleLandingPage -Path $OutputFolder ` + NewModuleLandingPage -Path $OutputFolder ` -ModulePagePath $ModulePagePath ` -ModuleName $ModuleName ` -ModuleGuid $ModuleGuid ` + -ModuleDescription $ModuleDescription ` + -ModuleVersion $ModuleVersion ` + -ModuleMetaData $ModuleMetaData ` -CmdletNames $CmdletNames ` + -MamlContents $MamlContents ` -Locale $Locale ` -Version $HelpVersion ` -FwLink $FwLink ` -Encoding $Encoding ` - -Force:$Force + -Force:$Force ` + -SkipEmptyFields:$SkipEmptyFields ` + -CreateTableOfContent:$CreateTableOfContent + } + else { + if ($PSCmdlet.ParameterSetName -eq 'FromModule') + { + if (-not (GetCommands -AsNames -module $_)) + { + throw $LocalizedData.ModuleNotFound -f $_ + } + + GetMamlObject -Session $Session -Module $_ -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields | processMamlObjectToFile + + $ModuleName = $_ + $ModObj = (Get-Module $ModuleName) + $ModuleGuid = $ModObj.Guid + $ModuleDescription = $ModObj.Description + if($null -ne $ModObj.Version) { + $ModuleVersion = $ModObj.Version.ToString() + } + if($null -ne $ModuleMetaData) { + + $ModuleMetaData.ModuleVersion = $ModuleVersion + $MetaDataGuid = $ModuleGuid.ToString() + if(![string]::IsNullOrWhiteSpace($MetaDataGuid)) { + $ModuleMetaData.GUID = $MetaDataGuid + } + if(![string]::IsNullOrWhiteSpace($ModObj.Author)) { + $ModuleMetaData.Author = $ModObj.Author + } + if(![string]::IsNullOrWhiteSpace($ModObj.CompanyName)) { + $ModuleMetaData.CompanyName = $ModObj.CompanyName + } + if(![string]::IsNullOrWhiteSpace($ModObj.Copyright)) { + $ModuleMetaData.Copyright = $ModObj.Copyright + } + if(![string]::IsNullOrWhiteSpace($ModObj.ReleaseNotes)) { + $ModuleMetaData.ReleaseNotes = $ModObj.ReleaseNotes + } + if($null -ne $ModObj.Tags) { + $FilteredTags = @($ModObj.Tags | Where-Object { ![string]::IsNullOrWhiteSpace($_) } | Sort-Object -Unique) + if($FilteredTags.Count -gt 0) { + $ModuleMetaData.Tags = @($FilteredTags) + } + } + if($null -ne $ModObj.LicenseUri -and ![string]::IsNullOrWhiteSpace($ModObj.LicenseUri.OriginalString)) { + $ModuleMetaData.LicenseUri = $ModObj.LicenseUri.OriginalString.Trim() + } + if($null -ne $ModObj.ProjectUri -and ![string]::IsNullOrWhiteSpace($ModObj.ProjectUri.OriginalString)) { + $ModuleMetaData.ProjectUri = $ModObj.ProjectUri.OriginalString.Trim() + } + $ModuleMetaData.RequiredModules = @($ModObj.RequiredModules) + $ModuleMetaData.RequiredAssemblies = @($ModObj.RequiredAssemblies) + } + $CmdletNames = GetCommands -AsNames -Module $ModuleName + } + else # 'FromMaml' + { + # Set ModuleName to MamlModule (since it's set to null at the beginning now) + $ModuleName = "MamlModule" + + if (-not (Test-Path $_)) + { + throw $LocalizedData.FileNotFound -f $_ + } + + GetMamlObject -MamlFile $_ -ConvertNotesToList:$ConvertNotesToList -ConvertDoubleDashLists:$ConvertDoubleDashLists -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields | processMamlObjectToFile + + $CmdletNames += GetMamlObject -MamlFile $_ -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields | ForEach-Object {$_.Name} + } + + if($WithModulePage) + { + if(-not $ModuleGuid) + { + $ModuleGuid = "00000000-0000-0000-0000-000000000000" + } + if($ModuleGuid.Count -gt 1) + { + Write-Warning -Message $LocalizedData.MoreThanOneGuid + } + + # yeild + NewModuleLandingPage -Path $OutputFolder ` + -ModulePagePath $ModulePagePath ` + -ModuleName $ModuleName ` + -ModuleGuid $ModuleGuid ` + -ModuleDescription $ModuleDescription ` + -ModuleVersion $ModuleVersion ` + -ModuleMetaData $ModuleMetaData ` + -CmdletNames $CmdletNames ` + -Locale $Locale ` + -Version $HelpVersion ` + -FwLink $FwLink ` + -Encoding $Encoding ` + -Force:$Force ` + -SkipEmptyFields:$SkipEmptyFields ` + -CreateTableOfContent:$CreateTableOfContent + } } } } @@ -378,7 +600,9 @@ function Update-MarkdownHelp [switch]$UpdateInputOutput, [Switch]$Force, [System.Management.Automation.Runspaces.PSSession]$Session, - [switch]$ExcludeDontShow + [switch]$ExcludeDontShow, + [switch]$NoInputOutputFormatting, + [switch]$SkipEmptyFields ) begin @@ -456,8 +680,8 @@ function Update-MarkdownHelp # update the help file entry in the metadata $metadata = Get-MarkdownMetadata $filePath - $metadata["external help file"] = GetHelpFileName $command - $reflectionModel = GetMamlObject -Session $Session -Cmdlet $name -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow.IsPresent + $metadata[$script:EXTERNAL_HELP_FILE_YAML_HEADER] = GetHelpFileName $command + $reflectionModel = GetMamlObject -Session $Session -Cmdlet $name -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields $metadata[$script:MODULE_PAGE_MODULE_NAME] = $reflectionModel.ModuleName $merger = New-Object Markdown.MAML.Transformer.MamlModelMerger -ArgumentList $infoCallback @@ -468,7 +692,7 @@ function Update-MarkdownHelp SortParamsAlphabetically $newModel } - $md = ConvertMamlModelToMarkdown -mamlCommand $newModel -metadata $metadata -PreserveFormatting + $md = ConvertMamlModelToMarkdown -mamlCommand $newModel -metadata $metadata -PreserveFormatting -NoInputOutputFormatting:$NoInputOutputFormatting MySetContent -path $file.FullName -value $md -Encoding $Encoding -Force # yield } } @@ -493,6 +717,8 @@ function Merge-MarkdownHelp [Switch]$Force, + [switch]$NoInputOutputFormatting, + [string]$MergeMarker = "!!! " ) @@ -573,7 +799,7 @@ function Merge-MarkdownHelp $merger = New-Object Markdown.MAML.Transformer.MamlMultiModelMerger -ArgumentList $null, (-not $ExplicitApplicableIfAll), $MergeMarker $newModel = $merger.Merge($dict) - $md = ConvertMamlModelToMarkdown -mamlCommand $newModel -metadata $newMetadata -PreserveFormatting + $md = ConvertMamlModelToMarkdown -mamlCommand $newModel -metadata $newMetadata -PreserveFormatting -NoInputOutputFormatting:$NoInputOutputFormatting $outputFilePath = Join-Path $OutputPath $groupName MySetContent -path $outputFilePath -value $md -Encoding $Encoding -Force:$Force # yeild } @@ -600,7 +826,8 @@ function Update-MarkdownHelpModule [switch]$UpdateInputOutput, [switch]$Force, [System.Management.Automation.Runspaces.PSSession]$Session, - [switch]$ExcludeDontShow + [switch]$ExcludeDontShow, + [switch]$SkipEmptyFields ) begin @@ -677,7 +904,7 @@ function Update-MarkdownHelpModule $MamlModel = New-Object System.Collections.Generic.List[Markdown.MAML.Model.MAML.MamlCommand] $files = @() $MamlModel = GetMamlModelImpl $affectedFiles -ForAnotherMarkdown -Encoding $Encoding - NewModuleLandingPage -RefreshModulePage -ModulePagePath $ModulePagePath -Path $modulePath -ModuleName $module -Module $MamlModel -Encoding $Encoding -Force + NewModuleLandingPage -RefreshModulePage -ModulePagePath $ModulePagePath -Path $modulePath -ModuleName $module -Module $MamlModel -Encoding $Encoding -Force -SkipEmptyFields:$SkipEmptyFields } } } @@ -1955,18 +2182,30 @@ function NewModuleLandingPage [Parameter(mandatory=$true,ParameterSetName="NewLandingPage")] [string] $ModuleGuid, + [Parameter(mandatory=$false,ParameterSetName="NewLandingPage")] + [string] + $ModuleDescription, + [Parameter(mandatory=$false,ParameterSetName="NewLandingPage")] + [string] + $ModuleVersion, + [Parameter(mandatory=$false,ParameterSetName="NewLandingPage")] + [PSCustomObject] + $ModuleMetaData = $null, [Parameter(mandatory=$true,ParameterSetName="NewLandingPage")] [string[]] $CmdletNames, + [Parameter(mandatory=$false,ParameterSetName="NewLandingPage")] + [string[]] + $MamlContents = $null, [Parameter(mandatory=$true,ParameterSetName="NewLandingPage")] [string] $Locale, - [Parameter(mandatory=$true,ParameterSetName="NewLandingPage")] + [Parameter(mandatory=$false,ParameterSetName="NewLandingPage")] [string] - $Version, - [Parameter(mandatory=$true,ParameterSetName="NewLandingPage")] + $Version = $null, + [Parameter(mandatory=$false,ParameterSetName="NewLandingPage")] [string] - $FwLink, + $FwLink = $null, [Parameter(ParameterSetName="UpdateLandingPage")] [switch] $RefreshModulePage, @@ -1976,7 +2215,9 @@ function NewModuleLandingPage $Module, [Parameter(mandatory=$true)] [System.Text.Encoding]$Encoding = $script:UTF8_NO_BOM, - [switch]$Force + [switch]$Force, + [switch]$SkipEmptyFields, + [switch]$CreateTableOfContent ) begin @@ -1991,7 +2232,16 @@ function NewModuleLandingPage process { - $Description = $LocalizedData.Description + if($SkipEmptyFields.IsPresent) { + $Description = $null + } + else { + $Description = $LocalizedData.Description + } + + if(![string]::IsNullOrWhiteSpace($ModuleDescription)) { + $Description = $ModuleDescription.Trim() + } if($RefreshModulePage) { @@ -2023,38 +2273,192 @@ function NewModuleLandingPage } else { - $ModuleGuid = $LocalizedData.ModuleGuid - $FwLink = $LocalizedData.FwLink - $Version = $LocalizedData.Version - $Locale = $LocalizedData.Locale - $Description = $LocalizedData.Description + if($SkipEmptyFields.IsPresent) { + $ModuleGuid = $null + $FwLink = $null + $Version = $null + $Locale = $null + $Description = $null + } + else { + $ModuleGuid = $LocalizedData.ModuleGuid + $FwLink = $LocalizedData.FwLink + $Version = $LocalizedData.Version + $Locale = $LocalizedData.Locale + $Description = $LocalizedData.Description + } } } - $Content = "---`r`nModule Name: $ModuleName`r`nModule Guid: $ModuleGuid`r`nDownload Help Link: $FwLink`r`n" - $Content += "Help Version: $Version`r`nLocale: $Locale`r`n" + $Content = "---`r`n" + $Content += "Module Name: $ModuleName`r`n" + if(![string]::IsNullOrWhiteSpace($ModuleGuid)) { + $Content += "Module Guid: $ModuleGuid`r`n" + } + if(![string]::IsNullOrWhiteSpace($ModuleVersion)) { + $Content += "Module Version: $ModuleVersion`r`n" + } + if(![string]::IsNullOrWhiteSpace($FwLink)) { + $Content += "Download Help Link: $FwLink`r`n" + } + if(![string]::IsNullOrWhiteSpace($Version)) { + $Content += "Help Version: $Version`r`n" + } + if(![string]::IsNullOrWhiteSpace($Locale)) { + $Content += "Locale: $Locale`r`n" + } $Content += "---`r`n`r`n" - $Content += "# $ModuleName Module`r`n## Description`r`n" - $Content += "$Description`r`n`r`n## $ModuleName Cmdlets`r`n" + $Content += "# $ModuleName Module`r`n`r`n" + if(![string]::IsNullOrWhiteSpace($Description)) { + $Content += "## Description`r`n$Description`r`n`r`n" + } + if($null -ne $ModuleMetaData) { + $Content += "## Module Metadata`r`n" - if($RefreshModulePage) - { - $Module | ForEach-Object { - $command = $_ - if(-not $command.Synopsis) - { - $Content += "### [" + $command.Name + "](" + $command.Name + ".md)`r`n" + $LocalizedData.Description + "`r`n`r`n" + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.ModuleVersion)) { + $Content += "* Module version: " + $ModuleMetaData.ModuleVersion + "`r`n" + } + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.GUID)) { + $Content += "* Module GUID: " + $ModuleMetaData.GUID + "`r`n" + } + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.Author)) { + $Content += "* Author: " + $ModuleMetaData.Author + "`r`n" + } + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.CompanyName)) { + $Content += "* Company: " + $ModuleMetaData.CompanyName + "`r`n" + } + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.Copyright)) { + $Content += "* Copyright: " + $ModuleMetaData.Copyright + "`r`n" + } + if($ModuleMetaData.Tags.Count -gt 0) { + $Content += "* Tags: " + ($ModuleMetaData.Tags -join ", ") + "`r`n" + } + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.LicenseUri)) { + $Content += "* License Uri: " + $ModuleMetaData.LicenseUri + "`r`n" + } + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.ProjectUri)) { + $Content += "* Project Uri: " + $ModuleMetaData.ProjectUri + "`r`n" + } + $Content += "`r`n" + + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.ReleaseNotes)) { + $Content += "### Release Notes`r`n" + $Content += ($ModuleMetaData.ReleaseNotes -replace "\r\n", "
`r`n") + "`r`n`r`n" + } + + if($null -ne $ModuleMetaData.RequiredModules -and $ModuleMetaData.RequiredModules.Count -gt 0) { + $Content += "### Required Modules`r`n" + $ModuleMetaData.RequiredModules | ForEach-Object { + $Content += "* $($_.Name)" + if($null -ne $_.Version -and ![string]::IsNullOrWhiteSpace($_.Version.ToString())) { + $Content += " ($($_.Version.ToString()))" + } + $Content += "`r`n" } - else - { - $Content += "### [" + $command.Name + "](" + $command.Name + ".md)`r`n" + $command.Synopsis + "`r`n`r`n" + $Content += "`r`n" + } + if($null -ne $ModuleMetaData.RequiredAssemblies -and $ModuleMetaData.RequiredAssemblies.Count -gt 0) { + $Content += "### Required Assemblies`r`n" + $ModuleMetaData.RequiredAssemblies | ForEach-Object { + $Content += "* $_`r`n" } + $Content += "`r`n" + } + } + + if($CreateTableOfContent.IsPresent) { + $Content += "## Content`r`n" + $Content += "<<>>`r`n" + $ContentIndexCount = @{} + } + + $Content += "`r`n" + $Content += "## $ModuleName Cmdlets`r`n" + + if($null -ne $MamlContents -and $MamlContents.Count -gt 0) { + $MamlContents | ForEach-Object { + $Content += "$_`r`n`r`n" } } - else - { - $CmdletNames | ForEach-Object { - $Content += "### [" + $_ + "](" + $_ + ".md)`r`n" + $LocalizedData.Description + "`r`n`r`n" + else { + if($RefreshModulePage) + { + $Module | ForEach-Object { + $command = $_ + if(-not $command.Synopsis) + { + $Content += "### [" + $command.Name + "](" + $command.Name + ".md)`r`n" + if(!$SkipEmptyFields.IsPresent) { + $Content += $LocalizedData.Description + "`r`n" + } + $Content += "`r`n" + } + else + { + $Content += "### [" + $command.Name + "](" + $command.Name + ".md)`r`n" + $command.Synopsis + "`r`n`r`n" + } + } + } + else + { + $CmdletNames | ForEach-Object { + $Content += "### [" + $_ + "](" + $_ + ".md)`r`n" + if(!$SkipEmptyFields.IsPresent) { + $Content += $LocalizedData.Description + "`r`n" + } + $Content += "`r`n" + } + } + } + + if($CreateTableOfContent.IsPresent) { + $IndexContent = "" + $Matches = [RegEx]::Matches($Content, "^\s*(?##+)\s*(?.+)`$", [System.Text.RegularExpressions.RegexOptions]::Multiline) + + if($null -ne $Matches) { + foreach($SingleMatch in $Matches) { + if($SingleMatch.Success ` + -and $SingleMatch.Groups["indent"].Success ` + -and $SingleMatch.Groups["heading"].Success) { + $CntIndent = $SingleMatch.Groups["indent"].Value.Length-2 + $Name = $SingleMatch.Groups["heading"].Value.Trim() + + if(![string]::IsNullOrWhiteSpace($Name)) { + $OriginalLinkName = $Name.ToLower().Replace(" ", "-") + + if($OriginalLinkName -in $ContentIndexCount.Keys) { + $LinkName = $OriginalLinkName + "-" + $ContentIndexCount[$OriginalLinkName] + $ContentIndexCount[$OriginalLinkName]++ + } + else { + $LinkName = $OriginalLinkName + $ContentIndexCount[$LinkName] = 1 + } + + $LeadingSpaces = New-Object -TypeName string -ArgumentList " ", (2*$CntIndent) + $ListChar = "*" + <# + $ListNrMod = $CntIndent % 3 + if($ListNrMod -eq 1) { + $ListChar = "+" + } + elseIf($ListNrMod -eq 2) { + $ListChar = "-" + } + #> + + $IndexContent += $LeadingSpaces + $ListChar + " [" + $Name + "](#" + $LinkName + ")`r`n" + } + } + } + + if($null -ne $IndexContent) { + $IndexContent = $IndexContent.Trim() + + if(![string]::IsNullOrWhiteSpace($IndexContent)) { + $Content = $Content.Replace("<<>>", $IndexContent) + } + } } } @@ -2072,9 +2476,13 @@ function ConvertMamlModelToMarkdown [hashtable]$metadata, + [int]$rootLevel = 0, + [switch]$NoMetadata, - [switch]$PreserveFormatting + [switch]$PreserveFormatting, + + [switch]$NoInputOutputFormatting ) begin @@ -2088,11 +2496,11 @@ function ConvertMamlModelToMarkdown { if (($count++) -eq 0 -and (-not $NoMetadata)) { - return $r.MamlModelToString($mamlCommand, $metadata) + return $r.MamlModelToString($rootLevel, $mamlCommand, $metadata, $NoInputOutputFormatting.IsPresent) } else { - return $r.MamlModelToString($mamlCommand, $true) # skip version header + return $r.MamlModelToString($rootLevel, $mamlCommand, $true, $NoInputOutputFormatting.IsPresent) # skip version header } } } @@ -2351,7 +2759,8 @@ function GetMamlObject [parameter(parametersetname="Cmdlet")] [parameter(parametersetname="Module")] [System.Management.Automation.Runspaces.PSSession]$Session, - [switch]$ExcludeDontShow + [switch]$ExcludeDontShow, + [switch]$SkipEmptyFields ) function CommandHasAutogeneratedSynopsis @@ -2366,7 +2775,7 @@ function GetMamlObject Write-Verbose -Message ($LocalizedData.Processing -f $Cmdlet) $Help = Get-Help $Cmdlet $Command = MyGetCommand -Session $Session -Cmdlet $Cmdlet - return ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help) -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow + return ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help) -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields } elseif ($Module) { @@ -2378,7 +2787,7 @@ function GetMamlObject Write-Verbose -Message ("`t" + ($LocalizedData.Processing -f $Command.Name)) $Help = Get-Help $Command.Name # yield - ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help) -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow + ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help) -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields } } else # Maml @@ -2399,7 +2808,7 @@ function GetMamlObject } # yield - ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UseHelpForParametersMetadata -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow + ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UseHelpForParametersMetadata -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow -SkipEmptyFields:$SkipEmptyFields } } } @@ -2479,7 +2888,8 @@ function ConvertPsObjectsToMamlModel [switch]$UseHelpForParametersMetadata, [switch]$UsePlaceholderForSynopsis, [switch]$UseFullTypeName, - [switch]$ExcludeDontShow + [switch]$ExcludeDontShow, + [switch]$SkipEmptyFields ) function isCommonParameterName @@ -2590,7 +3000,12 @@ function ConvertPsObjectsToMamlModel #Get Description #Not provided by the command object. - $MamlCommandObject.Description = New-Object -TypeName Markdown.MAML.Model.Markdown.SectionBody ($LocalizedData.Description) + if($SkipEmptyFields.IsPresent) { + $MamlCommandObject.Description = $null + } + else { + $MamlCommandObject.Description = New-Object -TypeName Markdown.MAML.Model.Markdown.SectionBody ($LocalizedData.Description) + } #endregion @@ -2712,16 +3127,21 @@ function ConvertPsObjectsToMamlModel $ParameterObject.Description = if ([String]::IsNullOrEmpty($Parameter.HelpMessage)) { # additional new-lines are needed for Update-MarkdownHelp scenario. - switch ($Parameter.Name) - { - # we have well-known parameters and can generate a reasonable description for them - # https://github.com/PowerShell/platyPS/issues/211 - 'Confirm' { $LocalizedData.Confirm + "`r`n`r`n" } - 'WhatIf' { $LocalizedData.WhatIf + "`r`n`r`n" } - 'IncludeTotalCount' { $LocalizedData.IncludeTotalCount + "`r`n`r`n" } - 'Skip' { $LocalizedData.Skip + "`r`n`r`n" } - 'First' { $LocalizedData.First + "`r`n`r`n" } - default { ($LocalizedData.ParameterDescription -f $Parameter.Name) + "`r`n`r`n" } + if($SkipEmptyFields.IsPresent) { + $null + } + else { + switch ($Parameter.Name) + { + # we have well-known parameters and can generate a reasonable description for them + # https://github.com/PowerShell/platyPS/issues/211 + 'Confirm' { $LocalizedData.Confirm + "`r`n`r`n" } + 'WhatIf' { $LocalizedData.WhatIf + "`r`n`r`n" } + 'IncludeTotalCount' { $LocalizedData.IncludeTotalCount + "`r`n`r`n" } + 'Skip' { $LocalizedData.Skip + "`r`n`r`n" } + 'First' { $LocalizedData.First + "`r`n`r`n" } + default { ($LocalizedData.ParameterDescription -f $Parameter.Name) + "`r`n`r`n" } + } } } else @@ -2805,10 +3225,15 @@ function ConvertPsObjectsToMamlModel #Get Synopsis if ($UsePlaceholderForSynopsis) { - # Help object ALWAYS contains SYNOPSIS. - # If it's not available, it's auto-generated. - # We don't want to include auto-generated SYNOPSIS (see https://github.com/PowerShell/platyPS/issues/110) - $MamlCommandObject.Synopsis = New-Object -TypeName Markdown.MAML.Model.Markdown.SectionBody ($LocalizedData.Synopsis) + if($SkipEmptyFields.IsPresent) { + $MamlCommandObject.Synopsis = $null + } + else { + # Help object ALWAYS contains SYNOPSIS. + # If it's not available, it's auto-generated. + # We don't want to include auto-generated SYNOPSIS (see https://github.com/PowerShell/platyPS/issues/110) + $MamlCommandObject.Synopsis = New-Object -TypeName Markdown.MAML.Model.Markdown.SectionBody ($LocalizedData.Synopsis) + } } else { @@ -2822,7 +3247,7 @@ function ConvertPsObjectsToMamlModel } #Get Description - if($Help.description -ne $null) + if($null -ne $Help.description) { $MamlCommandObject.Description = New-Object -TypeName Markdown.MAML.Model.Markdown.SectionBody ( $Help.description | @@ -2863,15 +3288,20 @@ function ConvertPsObjectsToMamlModel { $MamlExampleObject = New-Object -TypeName Markdown.MAML.Model.MAML.MamlExample - $MamlExampleObject.Introduction = $Example.introduction + $MamlExampleObject.Introduction = $Example.introduction | + DescriptionToPara | + AddLineBreaksForParagraphs + + $MamlExampleObject.Introduction = @($MamlExampleObject.Introduction | Where-Object { $_ -ne "PS >" -and $_ -ne "PS>" -and $_ -ne "PS C:\>"}) + $MamlExampleObject.Title = $Example.title $MamlExampleObject.Code = @( New-Object -TypeName Markdown.MAML.Model.MAML.MamlCodeBlock ($Example.code, '') - ) + ) $RemarkText = $Example.remarks | - DescriptionToPara | - AddLineBreaksForParagraphs + DescriptionToPara | + AddLineBreaksForParagraphs $MamlExampleObject.Remarks = $RemarkText $MamlCommandObject.Examples.Add($MamlExampleObject) @@ -2885,7 +3315,7 @@ function ConvertPsObjectsToMamlModel $Help.inputTypes.inputType | ForEach-Object { $InputDescription = $_.description $inputtypes = $_.type.name - if ($_.description -eq $null -and $_.type.name -ne $null) + if ($null -eq $_.description -and $null -ne $_.type.name) { $inputtypes = $_.type.name.split("`n", [System.StringSplitOptions]::RemoveEmptyEntries) } @@ -2912,7 +3342,7 @@ function ConvertPsObjectsToMamlModel $Help.returnValues.returnValue | ForEach-Object { $OuputDescription = $_.description $Outputtypes = $_.type.name - if ($_.description -eq $null -and $_.type.name -ne $null) + if ($null -eq $_.description -and $null -ne $_.type.name) { $Outputtypes = $_.type.name.split("`n", [System.StringSplitOptions]::RemoveEmptyEntries) } diff --git a/test/Markdown.MAML.Test/EndToEnd/EndToEndTests.cs b/test/Markdown.MAML.Test/EndToEnd/EndToEndTests.cs index ef7dff64..d45f9b75 100644 --- a/test/Markdown.MAML.Test/EndToEnd/EndToEndTests.cs +++ b/test/Markdown.MAML.Test/EndToEnd/EndToEndTests.cs @@ -71,6 +71,123 @@ And this is my last line. Assert.Equal(3, description.Length); } + [Fact] + public void PreserveMarkdownWhenUpdatingMarkdownHelpWithoutNotesOrLinks() + { + var expected = @"# Update-MarkdownHelp + +## SYNOPSIS + +Example markdown to test that markdown is preserved. + +## SYNTAX + +``` +Update-MarkdownHelp [-Name] [-Path ] +``` + +## DESCRIPTION +When calling Update-MarkdownHelp line breaks should be preserved. + +## EXAMPLES + +### Example 1: With no line break or description +```powershell +PS C:\> Write-Host 'This is output.' +``` + +``` +This is output. +``` + +This is example 1 remark. + +### Example 2: With no line break +This is an example description. + +```powershell +PS C:\> Update-MarkdownHelp +``` + +This is example 2 remark. + +### Example 3: With line break and no description + +```powershell +PS C:\> Update-MarkdownHelp +``` + +This is example 3 remark. + +### Example 4: With line break and description + +This is an example description. + +```preserve +PS C:\> Update-MarkdownHelp +``` + +```text +Output +``` + +This is example 4 remark. + +## PARAMETERS + +### -Name + +Parameter name description with line break. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Parameter path description with no line break. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +## INPUTS + +### String[] + +This is an input description. + +## OUTPUTS + +### System.Object + +This is an output description. + +"; + + // Parse markdown and convert back to markdown to make sure there are no changes + var actualFull = MarkdownStringToMarkdownString(expected, ParserMode.Full); + var actualFormattingPreserve = MarkdownStringToMarkdownString(expected, ParserMode.FormattingPreserve); + + Common.AssertMultilineEqual(expected, actualFull); + Common.AssertMultilineEqual(expected, actualFormattingPreserve); + } + [Fact] public void PreserveMarkdownWhenUpdatingMarkdownHelp() { @@ -180,7 +297,12 @@ This is an output description. ## NOTES +These are test notes + ## RELATED LINKS + +http://www.google.com +http://www.microsoft.com "; // Parse markdown and convert back to markdown to make sure there are no changes diff --git a/test/Markdown.MAML.Test/Renderer/MarkdownV2RendererTests.cs b/test/Markdown.MAML.Test/Renderer/MarkdownV2RendererTests.cs index 9e060567..4206bd2f 100644 --- a/test/Markdown.MAML.Test/Renderer/MarkdownV2RendererTests.cs +++ b/test/Markdown.MAML.Test/Renderer/MarkdownV2RendererTests.cs @@ -263,6 +263,42 @@ public void RendersExamplesFromMaml() Assert.Contains($"### {example7.Title}\r\n", markdown); } + [Fact] + public void RendererCreatesWorkflowParametersEntryWithoutDescriptions() + { + var renderer = new MarkdownV2Renderer(ParserMode.Full); + MamlCommand command = new MamlCommand() + { + Name = "Workflow", + IsWorkflow = true + }; + + command.Syntax.Add(new MamlSyntax()); + + string markdown = renderer.MamlModelToString(command, null); + Common.AssertMultilineEqual(@"--- +schema: 2.0.0 +--- + +# Workflow + +## SYNTAX + +``` +Workflow [] [] +``` + +## PARAMETERS + +### WorkflowCommonParameters +This cmdlet supports the following workflow common parameters: -PSParameterCollection, -PSComputerName, -PSCredential, -PSConnectionRetryCount, -PSConnectionRetryIntervalSec, -PSRunningTimeoutSec, -PSElapsedTimeoutSec, -PSPersist, -PSAuthentication, -PSAuthenticationLevel, -PSApplicationName, -PSPort, -PSUseSSL, -PSConfigurationName, -PSConnectionURI, -PSAllowRedirection, -PSSessionOption, -PSCertificateThumbprint, -PSPrivateMetadata, -AsJob, -JobName, and -InputObject. For more information, see [about_WorkflowCommonParameters](http://go.microsoft.com/fwlink/p/?LinkID=533952). + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +", markdown); + } + [Fact] public void RendererCreatesWorkflowParametersEntry() { @@ -270,6 +306,8 @@ public void RendererCreatesWorkflowParametersEntry() MamlCommand command = new MamlCommand() { Name = "Workflow", + Synopsis = new SectionBody("Example synopsis", SectionFormatOption.LineBreakAfterHeader), + Description = new SectionBody("Example description", SectionFormatOption.LineBreakAfterHeader), IsWorkflow = true }; @@ -284,6 +322,8 @@ public void RendererCreatesWorkflowParametersEntry() ## SYNOPSIS +Example synopsis + ## SYNTAX ``` @@ -292,7 +332,7 @@ Workflow [] [] ## DESCRIPTION -## EXAMPLES +Example description ## PARAMETERS @@ -302,13 +342,34 @@ Workflow [] [] ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). -## INPUTS +", markdown); + } -## OUTPUTS + [Fact] + public void RendererNormalizeQuotesAndDashesWithoutDescriptions() + { + var renderer = new MarkdownV2Renderer(ParserMode.Full); + MamlCommand command = new MamlCommand() + { + Name = "Test-Quotes", + Description = new SectionBody(@"”“‘’––-") + }; -## NOTES + string markdown = renderer.MamlModelToString(command, null); + Common.AssertMultilineEqual(@"--- +schema: 2.0.0 +--- + +# Test-Quotes + +## DESCRIPTION +""""''--- + +## PARAMETERS + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). -## RELATED LINKS ", markdown); } @@ -319,6 +380,7 @@ public void RendererNormalizeQuotesAndDashes() MamlCommand command = new MamlCommand() { Name = "Test-Quotes", + Synopsis = new SectionBody("Example synopsis", SectionFormatOption.LineBreakAfterHeader), Description = new SectionBody(@"”“‘’––-") }; @@ -331,25 +393,16 @@ public void RendererNormalizeQuotesAndDashes() ## SYNOPSIS -## SYNTAX +Example synopsis ## DESCRIPTION """"''--- -## EXAMPLES - ## PARAMETERS ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS ", markdown); } @@ -537,6 +590,8 @@ public void RenderesAllParameterSetMoniker() MamlCommand command = new MamlCommand() { Name = "Get-Foo", + Synopsis = new SectionBody("Example synopsis", SectionFormatOption.LineBreakAfterHeader), + Description = new SectionBody("Example description", SectionFormatOption.LineBreakAfterHeader), }; var commonParam = new MamlParameter() @@ -593,6 +648,8 @@ public void RenderesAllParameterSetMoniker() ## SYNOPSIS +Example synopsis + ## SYNTAX ### FirstSyntax @@ -607,7 +664,7 @@ public void RenderesAllParameterSetMoniker() ## DESCRIPTION -## EXAMPLES +Example description ## PARAMETERS @@ -653,13 +710,6 @@ public void RenderesAllParameterSetMoniker() ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS ", markdown); } @@ -698,23 +748,9 @@ With all [hyper](https://links.com) and yada # Get-Foo -## SYNOPSIS - -## SYNTAX - ## DESCRIPTION " + command.Description + @" -## EXAMPLES - -## PARAMETERS - -## INPUTS - -## OUTPUTS - -## NOTES - ## RELATED LINKS Any text [can](go here)