Write-CommandBlogPost

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(“&”, “&amp;”).Replace(“<“, “&lt;”).Replace(“>”,”&gt;”))
}
</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