On the PowerShell team, we’re big believers in the Virtuous Cycle. As you learn PowerShell more and more, things should get easier and easier to do. Inline help is a great example of the virtuous cycle, because it allows you to write scripts in such a way that they’re easy to learn about the same way you learn about most things in PowerShell (with Get-Help).
The other great source of learning material for PowerShell is the Internet, and our vibrant PowerShell community. Write-CommandBlogPost is designed to give you an extra benefit of writing help for your commands: you can use this function to (almost) automatically blog them out to the rest of the world.
Write-CommandBlogPost allows you to blog out help for a command and the command’s definition in a convenient format, so that you can spend more time making good scripts and less time explaining them to the rest of the world. Believe it or not, you’re actually reading the output of Write-CommandBlogPost right now. If you don’t like the output of Write-CommandBlogPost, you can always tweak the script to your liking.
It’s things like this that make me think PowerShell is really, really, cool language.
Write-CommandBlogPost
Synopsis:
Writes a draft of a blog post for a PowerShell function or cmdlet
Syntax:
Write-CommandBlogPost [-excludeSynopsis] [-excludeSyntax] [-excludeDescription] [-excludeExamples] [-excludeNotes] [-excludeParameters] [-excludeFunction] [-includeCss] [-separator [<Object>]] [-header [<Object>]] [-footer [<Object>]] [-Verbose] [-Debug] [-ErrorAction [<ActionPreference>]] [-WarningAction [<ActionPreference>]] [-ErrorVariable [<String>]] [-WarningVariable [<String>]] [-OutVariable [<String>]] [-OutBuffer [<Int32>]] [<CommonParameters>]
Write-CommandBlogPost [-command [<Object>]] [-excludeSynopsis] [-excludeSyntax] [-excludeDescription] [-excludeExamples] [-excludeNotes] [-excludeParameters] [-excludeFunction] [-includeCss] [-separator [<Object>]] [-header [<Object>]] [-footer [<Object>]] [-Verbose] [-Debug] [-ErrorAction [<ActionPreference>]] [-WarningAction [<ActionPreference>]] [-ErrorVariable [<String>]] [-WarningVariable [<String>]] [-OutVariable [<String>]] [-OutBuffer [<Int32>]] [<CommonParameters>]
Detailed Description:
Uses the help information for a command to generate a web page containing
the synopsis, description, examples, notes, parameters, and function body
of a command, as well as an optional header and footer. This encourages
individuals and organizations who write scripts to provide good help, and
saves time in evangelizing commands that have help.
Examples:
————————– EXAMPLE 1 ————————–# Writes a blog post about Write-CommandBlogPost and outputs it to a file. $header = ” On the PowerShell team, we’re big believers in the Virtuous Cycle. As you learn PowerShell more and more, things should get easier and easier to do. Inline help is a great example of the virtuous cycle, because it allows you to write scripts in such a way that they’re easy to learn about the same way you learn about most things in PowerShell (with Get-Help).”,” The other great source of learning material for PowerShell is the Internet, and our vibrant PowerShell community. Write-CommandBlogPost is designed to give you an extra benefit of writing help for your commands: you can use this function to (almost) automatically blog them out to the rest of the world.”,” Write-CommandBlogPost allows you to blog out help for a command and the command’s definition in a convenient format, so that you can spend more time making good scripts and less time explaining them to the rest of the world. Believe it or not, you’re actually reading the output of Write-CommandBlogPost right now. If you don’t like the output of Write-CommandBlogPost, you can always tweak the script to your liking. “,” It’s things like this that make me think PowerShell is really, really, cool language.” Write-CommandBlogPost Write-CommandBlogPost -includeCss -header $header -footer “Hope this Helps,”, “James Brundage [MSFT]” > Write-CommandBlogPost.htm
Command Parameters:
Name Description command The command to write a blog post on. This can be either a cmdlet or an advanced function that has provided detailed help excludeSynopsis If -excludeSynopsis is set, the Synopsis will be excluded from the output excludeSyntax If -excludeSyntax is set, the Syntax will be excluded from the output excludeDescription If -excludeDescription is set, the Description will be excluded from the output excludeExamples If -excludeExamples is set, the examples will be excluded from the output excludeNotes If -excludeNotes is set, the notes will be excluded from the output excludeParameters If -excludeParameters is set, the parameters will be excluded from the output excludeFunction If -excludeFunction is set, the function definition will be excluded from the output. This parameter has no effect if Write-CommandBlogPost is used on a compiled Cmdlet includeCss If -includeCss is set, then the outputted HTML will include a style section to help format the webpage separator By changing the separator, you change what separates different sections of the blog post. By default, the separator is a newline. header The header is content that will be displayed before the blog post, such as an introductory paragraph footer The footer is content that will be displayed after the blog post, such as a closing paragraph or signatur e
Here’s Write-CommandBlogPost:
function Write-CommandBlogPost {
<# .Synopsis Writes a draft of a blog post for a PowerShell function or cmdlet .Description Uses the help information for a command to generate a web page containing the synopsis, description, examples, notes, parameters, and function body of a command, as well as an optional header and footer. This encourages individuals and organizations who write scripts to provide good help, and saves time in evangelizing commands that have help. .Parameter Command The command to write a blog post on. This can be either a cmdlet or an advanced function that has provided detailed help .Parameter excludeSynopsis If -excludeSynopsis is set, the Synopsis will be excluded from the output .Parameter excludeSyntax If -excludeSyntax is set, the Syntax will be excluded from the output .Parameter excludeDescription If -excludeDescription is set, the Description will be excluded from the output .Parameter excludeExamples If -excludeExamples is set, the examples will be excluded from the output .Parameter excludeNotes If -excludeNotes is set, the notes will be excluded from the output .Parameter excludeParameters If -excludeParameters is set, the parameters will be excluded from the output .Parameter excludeFunction If -excludeFunction is set, the function definition will be excluded from the output. This parameter has no effect if Write-CommandBlogPost is used on a compiled Cmdlet .Parameter includeCss If -includeCss is set, then the outputted HTML will include a style section to help format the webpage .Parameter separator By changing the separator, you change what separates different sections of the blog post. By default, the separator is a newline. .Parameter header The header is content that will be displayed before the blog post, such as an introductory paragraph .Parameter footer The footer is content that will be displayed after the blog post, such as a closing paragraph or signature .Example # Writes a blog post about Write-CommandBlogPost and outputs it to a file. $header = ” On the PowerShell team, we’re big believers in the Virtuous Cycle. As you learn PowerShell more and more, things should get easier and easier to do. Inline help is a great example of the virtuous cycle, because it allows you to write scripts in such a way that they’re easy to learn about the same way you learn about most things in PowerShell (with Get-Help).”,” The other great source of learning material for PowerShell is the Internet, and our vibrant PowerShell community. Write-CommandBlogPost is designed to give you an extra benefit of writing help for your commands: you can use this function to (almost) automatically blog them out to the rest of the world.”,” Write-CommandBlogPost allows you to blog out help for a command and the command’s definition in a convenient format, so that you can spend more time making good scripts and less time explaining them to the rest of the world. Believe it or not, you’re actually reading the output of Write-CommandBlogPost right now. If you don’t like the output of Write-CommandBlogPost, you can always tweak the script to your liking. “,” It’s things like this that make me think PowerShell is really, really, cool language.” Write-CommandBlogPost Write-CommandBlogPost -includeCss -header $header -footer “Hope this Helps,”, “James Brundage [MSFT]” > Write-CommandBlogPost.htm #> param( [Parameter(ParameterSetName=’Command’, ValueFromPipeline=$true, ValueFromRemainingArguments=$true)] $command, [switch]$excludeSynopsis, [switch]$excludeSyntax, [switch]$excludeDescription, [switch]$excludeExamples, [switch]$excludeNotes, [switch]$excludeParameters, [switch]$excludeFunction, [switch]$includeCss, $separator = “<BR />”, $header, $footer ) begin {
if ($includeCss) { ” <style> .CmdletName { font-size:large } .CmdletSynopsis { font-size:medium } .CmdletDescription { font-size:medium } .CmdletParameters { font-size:medium } th { font-size: medium; font-style: italic } table { border: 1 } </style> ” } $originalOFS = $ofs $ofs = ” ” $realHeader = “” if ($header) { $header | Foreach-Object { $realHeader+=”<p class=’PostHeader’>$(($_ | Out-String -Width 10000).Trim())</p>” } } $realHeader
} process {
foreach ($c in $command) { if ($c -isnot [Management.Automation.CommandInfo]) { $realC = Get-Command $c } else { $realC = $c } $realC | Foreach-Object { $parameterSection = $null $synopsisSection = $null $syntaxSection = $null $descriptionSection = $null $definitionSection = $null $notesSection = $null $exampleSection = $null $nameSection = “<p class=’CmdletName’>$($_.Name)</p>” $help = $_ | Get-Help -ErrorAction SilentlyContinue if ($help) { $parametersDescribed = $help.Parameters.Parameter | Where-Object { $_.Description } if (-not $excludeParameters -and $parametersDescribed ) { $parameterTable = $help.Parameters.Parameter | Select-Object @{ Name=’Name’ Expression={$_.Name} }, @{ Name=’Description’ Expression={($_.Description | Out-String).Trim()} } | ConvertTo-Html -Fragment $parameterSection = ” <p class=’CmdletParameters’> Command Parameters: <blockquote> $parameterTable </blockquote> </p> ” } if (-not $excludeSynopsis -and $help.Synopsis) { $synopsisSection = ” <p class=’CmdletSynopsis’> <b>Synopsis:</b><BR /> <blockquote> $(($help.Synopsis | Out-String -Width 10000).Trim()) </blockquote> </p> ” } if (-not $excludeSyntax -and $help.Syntax) { $syntaxSection = ” <p class=’CmdletSyntax’><b>Syntax:</b><BR /> <blockquote> $([Security.SecurityElement]::Escape(($help.Syntax | Out-String -Width 10000).Trim()).Replace([Environment]::Newline, ‘<BR />’)) </blockquote> </p>” } if (-not $excludeDescription -and $help.Description) { $descriptionSection = ” <p class=’CmdletDescription’><b>Detailed Description:</b><BR /> <blockquote> $(($help.Description | Out-String -Width 10000).Trim().Replace([Environment]::Newline, ‘<BR />’)) </blockquote> </p>” } if (-not $excludeNotes -and $help.AlertSet){ $notesSection = ” <p class=’CmdletNotes’> <b>Notes:</b><BR /> <blockquote> $(($help.AlertSet | Out-String -Width 10000).Trim().Replace([Environment]::Newline, ‘<BR />’)) </blockquote> </p>” } if (-not $excludeExamples -and $help.Examples) { $exampleText = “” $help.Examples.Example | Foreach-Object { $exampleText+=” <blockquote> <pre class=’CmdletExample’> $(($_ |Out-String -Width 10000).Trim()) </pre> </blockquote> ” } $exampleSection = ” <p class=’Examples’> Examples:
$exampleText </p>” } } if ($_.ScriptBlock -and (-not $excludeFunction)) { $definitionSection = ” <p> Here’s $($_.Name): <i> <blockquote> <pre class=’CmdletDefinition’> function $($_.Name) { $($_.ScriptBlock.ToString().Replace(“&”, “&”).Replace(“<“, “<”).Replace(“>”,”>”)) } </pre> </blockquote> </i> </p>” } $oldOfs = $ofs $realFooter = “” if ($footer) { $footer | Foreach-Object { $realfooter+=”<p class=’Postfooter’>$(($_ | Out-String -Width 10000).Trim())</p>” } } $ofs = $separator “$($nameSection, $synopsisSection, $syntaxSection, $descriptionSection, $notesSection, $exampleSection, $parameterSection, $definitionSection | Where-Object { $_ }) ” $ofs =$oldOFS } }
} end {
$realFooter = “” if ($footer) { $footer | Foreach-Object { $realfooter+=”<p class=’Postfooter’>$(($_ | Out-String -Width 10000).Trim())</p>” } } $realFooter “<p style=’font-size:xx-small’>Automatically generated with <a href=’http://blogs.msdn.com/powershell/archive/tags/Write-CommandBlogPost/default.aspx’>Write-CommandBlogPost</a></p>” $ofs = $originalOfs
}
}
Automatically generated with Write-CommandBlogPost
0 comments