Write-CommandBlogPost

seroha

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:













































NameDescription
commandThe command to write a blog post on. This can be either a cmdlet or an advanced function that has provided detailed help
excludeSynopsisIf -excludeSynopsis is set, the Synopsis will be excluded from the output
excludeSyntaxIf -excludeSyntax is set, the Syntax will be excluded from the output
excludeDescriptionIf -excludeDescription is set, the Description will be excluded from the output
excludeExamplesIf -excludeExamples is set, the examples will be excluded from the output
excludeNotesIf -excludeNotes is set, the notes will be excluded from the output
excludeParametersIf -excludeParameters is set, the parameters will be excluded from the output
excludeFunctionIf -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
includeCssIf -includeCss is set, then the outputted HTML will include a style section to help format the webpage
separatorBy changing the separator, you change what separates different sections of the blog post. By default, the separator is a newline.
headerThe header is content that will be displayed before the blog post, such as an introductory paragraph
footerThe 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

seroha

Follow    

No Comments.