From 27f70beaf3fda993a4bd3539589f751824b974c4 Mon Sep 17 00:00:00 2001 From: Markus Szumovski Date: Mon, 25 Jan 2021 16:03:26 +0100 Subject: [PATCH 1/7] Multiple changes/adaptions: * Sections, like for example Description, without data (and without example data due to new switch -SkipEmptyFields) will no longer be rendered * Added switch -SinglePage to cmdlet New-MarkdownHelp so all functions will be written into the same module markdown file (same name as module landing page would normally have), instead of writing every cmdlet into its own markdown file * Added switch -NoInputOutputFormatting to cmdlets New-MarkdownHelp, Update-MarkdownHelp and Merge-MarkdownHelp so Input/Output comments won't be formatted. This is because microsoft gives us no way to actually set the values in Input/Output correct (type, description) but will put everything written there into the "type" property, so all text will be formatted bold. So for this to work correctly (not as intended) this switch needs to be provided so everything in the Input/Output section will just be written as is, without any bold formatting. * Added switch -SkipEmptyFields to cmdlets New-MarkdownHelp, Update-MarkdownHelp and Update-MarkdownHelpModule which will omit example text for empty fields which were not provided/found and will instead just skip empty sections * Added switch -CreateTableOfContent to cmdlet New-MarkdownHelp which will create an additional table of content in the single- or module-landing-page. * Added switch -WithModuleMetaData to cmdlet New-MarkdownHelp which will add a section "Module Metadata" filled with the following data (as far as that data exists): Module version, Author, Company, Copyright, Tags, License Uri, Project Uri * Added module version to yaml metadata at beginning of markdown * Adapted UnitTests to work with removed empty sections (due to missing data) --- .../Renderer/Markdownv2Renderer.cs | 241 ++++--- src/platyPS/platyPS.psd1 | 3 +- src/platyPS/platyPS.psm1 | 617 +++++++++++++++--- .../EndToEnd/EndToEndTests.cs | 122 ++++ .../Renderer/MarkdownV2RendererTests.cs | 110 ++-- 5 files changed, 866 insertions(+), 227 deletions(-) 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/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..568cbe24 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 + } + } + } - MySetContent -path (Join-Path $OutputFolder "$commandName.md") -value $md -Encoding $Encoding -Force:$Force + 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[$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,79 @@ 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 + if($null -ne $ModuleGuid -and ![string]::IsNullOrWhiteSpace($ModuleGuid.Guid)) { + $ModuleMetaData.GUID = $ModuleGuid.Guid + } + 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 $_ + 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} } - GetMamlObject -MamlFile $_ -ConvertNotesToList:$ConvertNotesToList -ConvertDoubleDashLists:$ConvertDoubleDashLists -ExcludeDontShow:$ExcludeDontShow.IsPresent | processMamlObjectToFile - - $CmdletNames += GetMamlObject -MamlFile $_ -ExcludeDontShow:$ExcludeDontShow.IsPresent | ForEach-Object {$_.Name} - } - - if($WithModulePage) - { if(-not $ModuleGuid) { $ModuleGuid = "00000000-0000-0000-0000-000000000000" @@ -307,17 +421,117 @@ 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 + if($null -ne $ModuleGuid -and ![string]::IsNullOrWhiteSpace($ModuleGuid.Guid)) { + $ModuleMetaData.GUID = $ModuleGuid.Guid + } + 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' + { + 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 +592,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 +672,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 +684,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 +709,8 @@ function Merge-MarkdownHelp [Switch]$Force, + [switch]$NoInputOutputFormatting, + [string]$MergeMarker = "!!! " ) @@ -573,7 +791,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 +818,8 @@ function Update-MarkdownHelpModule [switch]$UpdateInputOutput, [switch]$Force, [System.Management.Automation.Runspaces.PSSession]$Session, - [switch]$ExcludeDontShow + [switch]$ExcludeDontShow, + [switch]$SkipEmptyFields ) begin @@ -677,7 +896,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 +2174,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 +2207,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 +2224,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 +2265,189 @@ 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" + if(![string]::IsNullOrWhiteSpace($Description)) { + $Content += "## Description`r`n$Description`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" + } + + if(![string]::IsNullOrWhiteSpace($ModuleMetaData.ReleaseNotes)) { + $Content += "### Release Notes`r`n" + $Content += $ModuleMetaData.ReleaseNotes + "`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" + } + if($null -ne $ModuleMetaData.RequiredAssemblies -and $ModuleMetaData.RequiredAssemblies.Count -gt 0) { + $Content += "### Required Assemblies`r`n" + $ModuleMetaData.RequiredAssemblies | ForEach-Object { + $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 +2465,13 @@ function ConvertMamlModelToMarkdown [hashtable]$metadata, + [int]$rootLevel = 0, + [switch]$NoMetadata, - [switch]$PreserveFormatting + [switch]$PreserveFormatting, + + [switch]$NoInputOutputFormatting ) begin @@ -2088,11 +2485,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 +2748,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 +2764,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 +2776,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 +2797,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 +2877,8 @@ function ConvertPsObjectsToMamlModel [switch]$UseHelpForParametersMetadata, [switch]$UsePlaceholderForSynopsis, [switch]$UseFullTypeName, - [switch]$ExcludeDontShow + [switch]$ExcludeDontShow, + [switch]$SkipEmptyFields ) function isCommonParameterName @@ -2590,7 +2989,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 +3116,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 +3214,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 +3236,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 +3277,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 +3304,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 +3331,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) From fe87f7423df6b74ada9f2337f76957e7a64e8edf Mon Sep 17 00:00:00 2001 From: Markus Szumovski Date: Tue, 26 Jan 2021 09:59:54 +0100 Subject: [PATCH 2/7] Bugfixing "MamlModule" part of New-MarkdownHelp --- src/platyPS/platyPS.psm1 | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/platyPS/platyPS.psm1 b/src/platyPS/platyPS.psm1 index 568cbe24..ca192f4b 100644 --- a/src/platyPS/platyPS.psm1 +++ b/src/platyPS/platyPS.psm1 @@ -403,6 +403,8 @@ function New-MarkdownHelp } else # 'FromMaml' { + $ModuleName = "MamlModule" + if (-not (Test-Path $_)) { throw $LocalizedData.FileNotFound -f $_ @@ -494,6 +496,8 @@ function New-MarkdownHelp } else # 'FromMaml' { + $ModuleName = "MamlModule" + if (-not (Test-Path $_)) { throw $LocalizedData.FileNotFound -f $_ From 6a61aea33dcbbe2293bf9054177a9c52dec918d9 Mon Sep 17 00:00:00 2001 From: Markus Szumovski Date: Tue, 26 Jan 2021 10:16:35 +0100 Subject: [PATCH 3/7] Updated help files --- docs/Get-HelpPreview.md | 3 - docs/Get-MarkdownMetadata.md | 3 - docs/Merge-MarkdownHelp.md | 20 +++++-- docs/New-ExternalHelp.md | 2 - docs/New-ExternalHelpCab.md | 2 - docs/New-MarkdownHelp.md | 91 ++++++++++++++++++++++++++++--- docs/New-YamlHelp.md | 3 - docs/Update-MarkdownHelp.md | 32 ++++++++++- docs/Update-MarkdownHelpModule.md | 18 +++++- 9 files changed, 148 insertions(+), 26 deletions(-) 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..dd8dce45 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 +{{ Fill NoInputOutputFormatting Description }} + +```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..ccc610bc 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 +{{ Fill CreateTableOfContent Description }} + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoInputOutputFormatting +{{ Fill NoInputOutputFormatting Description }} + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SinglePage +{{ Fill SinglePage Description }} + +```yaml +Type: SwitchParameter +Parameter Sets: FromModule, FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipEmptyFields +{{ Fill SkipEmptyFields Description }} + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WithModuleMetaData +{{ Fill WithModuleMetaData Description }} + +```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..0a93dff1 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 +{{ Fill NoInputOutputFormatting Description }} + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipEmptyFields +{{ Fill SkipEmptyFields Description }} + +```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..c46720a8 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 +{{ Fill SkipEmptyFields Description }} + +```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). From d300165c10f77ce8718bdc72e4044cba2a4c1eef Mon Sep 17 00:00:00 2001 From: Markus Szumovski Date: Tue, 26 Jan 2021 10:24:25 +0100 Subject: [PATCH 4/7] Added some comments to rerun pull request checks (seems there was a random error in the build, so we gotta restart it) --- src/platyPS/platyPS.psm1 | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/platyPS/platyPS.psm1 b/src/platyPS/platyPS.psm1 index ca192f4b..fa1058b1 100644 --- a/src/platyPS/platyPS.psm1 +++ b/src/platyPS/platyPS.psm1 @@ -403,6 +403,7 @@ function New-MarkdownHelp } else # 'FromMaml' { + # Set ModuleName to MamlModule (since it's set to null at the beginning now) $ModuleName = "MamlModule" if (-not (Test-Path $_)) @@ -496,6 +497,7 @@ function New-MarkdownHelp } else # 'FromMaml' { + # Set ModuleName to MamlModule (since it's set to null at the beginning now) $ModuleName = "MamlModule" if (-not (Test-Path $_)) From 49f649e2f20d7ed105eba5de9a78973f8383761c Mon Sep 17 00:00:00 2001 From: Markus Szumovski Date: Tue, 26 Jan 2021 11:00:40 +0100 Subject: [PATCH 5/7] Fixed Yaml rendering of empty notes/remarks/summary --- src/Markdown.MAML/Renderer/YamlRenderer.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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(), From e265fceb59577f8b84e7ff9cdef5fac791f41b82 Mon Sep 17 00:00:00 2001 From: Markus Szumovski Date: Fri, 29 Jan 2021 13:41:17 +0100 Subject: [PATCH 6/7] Fixed GUID output for switch WithModuleMetaData Added help for new switches --- docs/Merge-MarkdownHelp.md | 2 +- docs/New-MarkdownHelp.md | 10 +++++----- docs/Update-MarkdownHelp.md | 4 ++-- docs/Update-MarkdownHelpModule.md | 2 +- src/platyPS/platyPS.psm1 | 10 ++++++---- 5 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/Merge-MarkdownHelp.md b/docs/Merge-MarkdownHelp.md index dd8dce45..0773894a 100644 --- a/docs/Merge-MarkdownHelp.md +++ b/docs/Merge-MarkdownHelp.md @@ -142,7 +142,7 @@ Accept wildcard characters: True ``` ### -NoInputOutputFormatting -{{ Fill NoInputOutputFormatting Description }} +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 diff --git a/docs/New-MarkdownHelp.md b/docs/New-MarkdownHelp.md index ccc610bc..4dd5c931 100644 --- a/docs/New-MarkdownHelp.md +++ b/docs/New-MarkdownHelp.md @@ -495,7 +495,7 @@ Accept wildcard characters: False ``` ### -CreateTableOfContent -{{ Fill CreateTableOfContent Description }} +Will create an additional table of content in the single- or module-landing-page. ```yaml Type: SwitchParameter @@ -510,7 +510,7 @@ Accept wildcard characters: False ``` ### -NoInputOutputFormatting -{{ Fill NoInputOutputFormatting Description }} +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 @@ -525,7 +525,7 @@ Accept wildcard characters: False ``` ### -SinglePage -{{ Fill SinglePage Description }} +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 @@ -540,7 +540,7 @@ Accept wildcard characters: False ``` ### -SkipEmptyFields -{{ Fill SkipEmptyFields Description }} +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 @@ -555,7 +555,7 @@ Accept wildcard characters: False ``` ### -WithModuleMetaData -{{ Fill WithModuleMetaData Description }} +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 diff --git a/docs/Update-MarkdownHelp.md b/docs/Update-MarkdownHelp.md index 0a93dff1..59803c53 100644 --- a/docs/Update-MarkdownHelp.md +++ b/docs/Update-MarkdownHelp.md @@ -233,7 +233,7 @@ Accept wildcard characters: False ``` ### -NoInputOutputFormatting -{{ Fill NoInputOutputFormatting Description }} +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 @@ -248,7 +248,7 @@ Accept wildcard characters: False ``` ### -SkipEmptyFields -{{ Fill SkipEmptyFields Description }} +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 diff --git a/docs/Update-MarkdownHelpModule.md b/docs/Update-MarkdownHelpModule.md index c46720a8..50a1d6ca 100644 --- a/docs/Update-MarkdownHelpModule.md +++ b/docs/Update-MarkdownHelpModule.md @@ -241,7 +241,7 @@ Accept wildcard characters: False ``` ### -SkipEmptyFields -{{ Fill SkipEmptyFields Description }} +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 diff --git a/src/platyPS/platyPS.psm1 b/src/platyPS/platyPS.psm1 index fa1058b1..66a7838b 100644 --- a/src/platyPS/platyPS.psm1 +++ b/src/platyPS/platyPS.psm1 @@ -368,8 +368,9 @@ function New-MarkdownHelp if($null -ne $ModuleMetaData) { $ModuleMetaData.ModuleVersion = $ModuleVersion - if($null -ne $ModuleGuid -and ![string]::IsNullOrWhiteSpace($ModuleGuid.Guid)) { - $ModuleMetaData.GUID = $ModuleGuid.Guid + $MetaDataGuid = $ModuleGuid.ToString() + if(![string]::IsNullOrWhiteSpace($MetaDataGuid)) { + $ModuleMetaData.GUID = $MetaDataGuid } if(![string]::IsNullOrWhiteSpace($ModObj.Author)) { $ModuleMetaData.Author = $ModObj.Author @@ -463,8 +464,9 @@ function New-MarkdownHelp if($null -ne $ModuleMetaData) { $ModuleMetaData.ModuleVersion = $ModuleVersion - if($null -ne $ModuleGuid -and ![string]::IsNullOrWhiteSpace($ModuleGuid.Guid)) { - $ModuleMetaData.GUID = $ModuleGuid.Guid + $MetaDataGuid = $ModuleGuid.ToString() + if(![string]::IsNullOrWhiteSpace($MetaDataGuid)) { + $ModuleMetaData.GUID = $MetaDataGuid } if(![string]::IsNullOrWhiteSpace($ModObj.Author)) { $ModuleMetaData.Author = $ModObj.Author From 5877b1ab12cbf4fe3e5c98aa5c1a58afd8f7d634 Mon Sep 17 00:00:00 2001 From: Markus Szumovski Date: Fri, 29 Jan 2021 15:05:29 +0100 Subject: [PATCH 7/7] Fixed some formatting bugs --- src/platyPS/platyPS.psm1 | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/src/platyPS/platyPS.psm1 b/src/platyPS/platyPS.psm1 index 66a7838b..a0d35a77 100644 --- a/src/platyPS/platyPS.psm1 +++ b/src/platyPS/platyPS.psm1 @@ -2308,41 +2308,42 @@ function NewModuleLandingPage $Content += "Locale: $Locale`r`n" } $Content += "---`r`n`r`n" - $Content += "# $ModuleName Module`r`n" + $Content += "# $ModuleName Module`r`n`r`n" if(![string]::IsNullOrWhiteSpace($Description)) { - $Content += "## Description`r`n$Description`r`n" + $Content += "## Description`r`n$Description`r`n`r`n" } if($null -ne $ModuleMetaData) { $Content += "## Module Metadata`r`n" if(![string]::IsNullOrWhiteSpace($ModuleMetaData.ModuleVersion)) { - $Content += "Module version: " + $ModuleMetaData.ModuleVersion + "`r`n" + $Content += "* Module version: " + $ModuleMetaData.ModuleVersion + "`r`n" } if(![string]::IsNullOrWhiteSpace($ModuleMetaData.GUID)) { - $Content += "Module GUID: " + $ModuleMetaData.GUID + "`r`n" + $Content += "* Module GUID: " + $ModuleMetaData.GUID + "`r`n" } if(![string]::IsNullOrWhiteSpace($ModuleMetaData.Author)) { - $Content += "Author: " + $ModuleMetaData.Author + "`r`n" + $Content += "* Author: " + $ModuleMetaData.Author + "`r`n" } if(![string]::IsNullOrWhiteSpace($ModuleMetaData.CompanyName)) { - $Content += "Company: " + $ModuleMetaData.CompanyName + "`r`n" + $Content += "* Company: " + $ModuleMetaData.CompanyName + "`r`n" } if(![string]::IsNullOrWhiteSpace($ModuleMetaData.Copyright)) { - $Content += "Copyright: " + $ModuleMetaData.Copyright + "`r`n" + $Content += "* Copyright: " + $ModuleMetaData.Copyright + "`r`n" } if($ModuleMetaData.Tags.Count -gt 0) { - $Content += "Tags: " + ($ModuleMetaData.Tags -join ", ") + "`r`n" + $Content += "* Tags: " + ($ModuleMetaData.Tags -join ", ") + "`r`n" } if(![string]::IsNullOrWhiteSpace($ModuleMetaData.LicenseUri)) { - $Content += "License Uri: " + $ModuleMetaData.LicenseUri + "`r`n" + $Content += "* License Uri: " + $ModuleMetaData.LicenseUri + "`r`n" } if(![string]::IsNullOrWhiteSpace($ModuleMetaData.ProjectUri)) { - $Content += "Project Uri: " + $ModuleMetaData.ProjectUri + "`r`n" + $Content += "* Project Uri: " + $ModuleMetaData.ProjectUri + "`r`n" } + $Content += "`r`n" if(![string]::IsNullOrWhiteSpace($ModuleMetaData.ReleaseNotes)) { $Content += "### Release Notes`r`n" - $Content += $ModuleMetaData.ReleaseNotes + "`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) { @@ -2354,12 +2355,14 @@ function NewModuleLandingPage } $Content += "`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" } }