From f82d0e6147a58d74642a2191d4faca9811c79807 Mon Sep 17 00:00:00 2001 From: David Eberhardt Date: Sat, 9 Jan 2021 14:12:23 +0000 Subject: [PATCH 1/3] Markdownlint MD022 (Fixes #945, part 1) --- platyPS.schema.md | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/platyPS.schema.md b/platyPS.schema.md index 25b8d7f5..8c1ed0ef 100644 --- a/platyPS.schema.md +++ b/platyPS.schema.md @@ -11,7 +11,7 @@ It closely resembles output of `Get-Help`. * tabs show the scopes of `// for` statements; they should not be included in the Markdown output. ### Version 2.0.0 - + // Every cmdlet help placed in it's own `Command-Name.md` file in one folder. // We sometimes reference to this folder as "HelpModule". @@ -32,11 +32,13 @@ It closely resembles output of `Get-Help`. // following level-2 headers sections can go in any order // here is the recommended order - + ## SYNOPSIS + {{Synopsis text}} ## SYNTAX + // for each parameter set ### {Parameter Set Name, if default parameter set, followed by "(Default)"} // i.e.: FromPath (Default) @@ -47,21 +49,23 @@ It closely resembles output of `Get-Help`. ``` ## DESCRIPTION + {{Description text}} ## EXAMPLES + // for every example ### {Example Name} {{Example introduction text}} - + // one or more times, codesnippet // it's useful to put the ```powershell code // before the plain text command exectution output ```{Syntax language, i.e. PowerShell or nothing for plain text} {{Example body}} ``` - + {{Example remarks}} // not a mandatory, i.e. TechNet articles don't use remarks ## PARAMETERS @@ -72,7 +76,7 @@ It closely resembles output of `Get-Help`. {{Parameter description text. It can also include codesnippets, but they could not be ```yaml}} // parameter metadata - // for every unique parameter metadata set + // for every unique parameter metadata set // Note: two Parameter Sets can have the same parameter as mandatory and non-mandatory // then we put them in two yaml snippets. // If they have the same metadata, we put them in one yaml snippet. @@ -83,7 +87,7 @@ It closely resembles output of `Get-Help`. Accepted values: {ValidateSet, comma-separated list of valid values, i.e. Foo, Bar} // if ommitted => everything is accepted Applicable: {comma-separated list of tags where this cmdlet exists} // if omitted then applicable for any tag // break line to improve readability and separate metadata block - + Required: {true | false} Position: {1..n} | named Default value: {None | False (for switch parameters) | the actual default value} @@ -92,20 +96,25 @@ It closely resembles output of `Get-Help`. ``` // if supports workflow parameters ### + {{ Workflow common parameters text, would be ingored during maml generation }} // if supports common parameters ### + {{ Common parameters text, would be ingored during maml generation }} ## INPUTS // for every input type ### {Input type} + {{Description text}} ## OUTPUTS + // for every output type ### {Output type} + {{Description text}} ## RELATED LINKS @@ -114,18 +123,21 @@ It closely resembles output of `Get-Help`. [{link name}]({link url}) ### Version 1.0.0 (Deprecated) + v0.7.6 is the last platyPS version that supports it. // for every command: # {Command name} - + // following level-2 headers sections can go in any order // here is the recommended order - + ## SYNOPSIS + {{Synopsis text}} ## DESCRIPTION + {{Description text}} ## PARAMETERS @@ -144,16 +156,19 @@ v0.7.6 is the last platyPS version that supports it. {{Parameter description text}} ## INPUTS + // for every input type ### {Input type} {{Description text}} ## OUTPUTS + // for every output type ### {Output type} {{Description text}} ## EXAMPLES + // for every example ### {Example Name} From 2ded713d610ec3889ad54dfd5d09e2c2f4440e78 Mon Sep 17 00:00:00 2001 From: David Eberhardt <44290340+DEberhardt@users.noreply.github.com> Date: Sat, 9 Jan 2021 14:52:06 +0000 Subject: [PATCH 2/3] Update to address Language in Syntax bit (MD040) copied {Syntax language, i.e. PowerShell or nothing for plain text} to fence in Syntax --- platyPS.schema.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platyPS.schema.md b/platyPS.schema.md index 8c1ed0ef..469fa67d 100644 --- a/platyPS.schema.md +++ b/platyPS.schema.md @@ -44,7 +44,7 @@ It closely resembles output of `Get-Help`. // i.e.: FromPath (Default) // This syntax would be ignored during maml generation. // syntax would be generated from parameters metadata - ``` + ```{Syntax language, i.e. PowerShell or nothing for plain text} {{Output of Get-Command -Syntax}} ``` From f7c1d303314a4d2d7e9b13298eebdd84894ea92c Mon Sep 17 00:00:00 2001 From: David Eberhardt Date: Sat, 9 Jan 2021 18:45:56 +0000 Subject: [PATCH 3/3] schema and template --- platyPS.schema.md | 8 +++++++- templates/aboutTemplate.md | 9 +++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/platyPS.schema.md b/platyPS.schema.md index 8c1ed0ef..67fdd38d 100644 --- a/platyPS.schema.md +++ b/platyPS.schema.md @@ -41,10 +41,11 @@ It closely resembles output of `Get-Help`. // for each parameter set ### {Parameter Set Name, if default parameter set, followed by "(Default)"} + // i.e.: FromPath (Default) // This syntax would be ignored during maml generation. // syntax would be generated from parameters metadata - ``` + ```{Syntax language, i.e. PowerShell or nothing for plain text} {{Output of Get-Command -Syntax}} ``` @@ -73,6 +74,7 @@ It closely resembles output of `Get-Help`. // for every parameter // default value is non-mandatory ### -{Parameter name} + {{Parameter description text. It can also include codesnippets, but they could not be ```yaml}} // parameter metadata @@ -94,6 +96,7 @@ It closely resembles output of `Get-Help`. Accept pipeline input: {false | true (ByValue, ByPropertyName)} Accept wildcard characters: {true | false} ``` + // if supports workflow parameters ### @@ -105,6 +108,7 @@ It closely resembles output of `Get-Help`. {{ Common parameters text, would be ingored during maml generation }} ## INPUTS + // for every input type ### {Input type} @@ -159,11 +163,13 @@ v0.7.6 is the last platyPS version that supports it. // for every input type ### {Input type} + {{Description text}} ## OUTPUTS // for every output type + ### {Output type} {{Description text}} diff --git a/templates/aboutTemplate.md b/templates/aboutTemplate.md index d6ea723f..0e2951dc 100644 --- a/templates/aboutTemplate.md +++ b/templates/aboutTemplate.md @@ -1,4 +1,5 @@ # {{TOPIC NAME}} + ## {{FileNameForHelpSystem}} ``` @@ -17,6 +18,7 @@ The second header should have no spaces. ``` # SHORT DESCRIPTION + {{ Short Description Placeholder }} ``` @@ -27,28 +29,35 @@ The generated about topic will be encoded UTF-8. ``` # LONG DESCRIPTION + {{ Long Description Placeholder }} ## Optional Subtopics + {{ Optional Subtopic Placeholder }} # EXAMPLES + {{ Code or descriptive examples of how to leverage the functions described. }} # NOTE + {{ Note Placeholder - Additional information that a user needs to know.}} # TROUBLESHOOTING NOTE + {{ Troubleshooting Placeholder - Warns users of bugs}} {{ Explains behavior that is likely to change with fixes }} # SEE ALSO + {{ See also placeholder }} {{ You can also list related articles, blogs, and video URLs. }} # KEYWORDS + {{List alternate names or titles for this topic that readers might use.}} - {{ Keyword Placeholder }}