Merge pull request #234 from lipkau/feature/NewDocumentation

Migration to External Help

JiraPS.build.ps1

@@ -117,7 +117,7 @@ task InstallPandoc {
 task Build GenerateRelease, ConvertMarkdown, UpdateManifest
 
 # Synopsis: Generate ./Release structure
-task GenerateRelease {
+task GenerateRelease CreateHelp, {
     # Setup
     if (-not (Test-Path "$releasePath/$ModuleName")) {
         $null = New-Item -Path "$releasePath/$ModuleName" -ItemType Directory
@@ -139,6 +139,16 @@ task GenerateRelease {
     BuildHelpers\Update-Metadata -Path "$releasePath/PSScriptAnalyzerSettings.psd1" -PropertyName ExcludeRules -Value ''
 }
 
+# Synopsis: Use PlatyPS to generate External-Help
+task CreateHelp -If (Get-ChildItem "$BuildRoot/docs/en-US/commands" -ErrorAction SilentlyContinue) {
+    Import-Module platyPS -Force
+    foreach ($locale in (Get-ChildItem "$BuildRoot/docs" -Attribute Directory)) {
+        New-ExternalHelp -Path "$($locale.FullName)" -OutputPath "$BuildRoot/$ModuleName/$($locale.Basename)" -Force
+        New-ExternalHelp -Path "$($locale.FullName)/commands" -OutputPath "$BuildRoot/$ModuleName/$($locale.Basename)" -Force
+    }
+    Remove-Module $ModuleName, platyPS
+}
+
 # Synopsis: Update the manifest of the module
 task UpdateManifest GetVersion, {
     Remove-Module $ModuleName -ErrorAction SilentlyContinue
@@ -156,6 +166,9 @@ task UpdateManifest GetVersion, {
     if ($ModuleAlias) {
         BuildHelpers\Update-Metadata -Path "$releasePath/$ModuleName/$ModuleName.psd1" -PropertyName AliasesToExport -Value @($ModuleAlias.Name)
     }
+    else {
+        BuildHelpers\Update-Metadata -Path "$releasePath/$ModuleName/$ModuleName.psd1" -PropertyName AliasesToExport -Value ''
+    }
     BuildHelpers\Set-ModuleFunctions -Name "$releasePath/$ModuleName/$ModuleName.psd1" -FunctionsToExport ([string[]](Get-ChildItem "$releasePath/$ModuleName/public/*.ps1").BaseName)
 }
 

JiraPS/Public/Add-JiraGroupMember.ps1

@@ -1,36 +1,11 @@
 function Add-JiraGroupMember {
-    <#
-    .Synopsis
-       Adds a user to a JIRA group
-    .DESCRIPTION
-       This function adds a JIRA user to a JIRA group.
-    .EXAMPLE
-       Add-JiraGroupMember -Group testUsers -User jsmith
-       This example adds the user jsmith to the group testUsers
-    .EXAMPLE
-       Get-JiraGroup 'Project Admins' | Add-JiraGroupMember -User jsmith
-       This example illustrates the use of the pipeline to add jsmith to the
-       "Project Admins" group in JIRA.
-    .INPUTS
-       [JiraPS.Group[]] Group(s) to which users should be added
-    .OUTPUTS
-       If the -PassThru parameter is provided, this function will provide a
-       reference to the JIRA group modified.  Otherwise, this function does not
-       provide output.
-    .NOTES
-       This REST method is still marked Experimental in JIRA's REST API. That
-       means that there is a high probability this will break in future
-       versions of JIRA. The function will need to be re-written at that time.
-    #>
     [CmdletBinding( SupportsShouldProcess )]
     param(
-        # Group (or list of groups) to which the user(s) will be added.
         [Parameter( Mandatory, ValueFromPipeline )]
         [Alias('GroupName')]
         [Object[]]
         $Group,
 
-        # Username or user object obtained from Get-JiraUser.
         [Parameter( Mandatory )]
         [Object[]]
         $UserName,
@@ -39,12 +14,9 @@ function Add-JiraGroupMember {
           Once we have custom classes, this can also accept ValueFromPipeline
         #>
 
-        # Credentials to use to connect to JIRA.
-        # If not specified, this function will use anonymous access.
         [PSCredential]
         $Credential,
 
-        # Whether output should be provided after invoking this function.
         [Switch]
         $PassThru
     )

JiraPS/Public/Add-JiraIssueAttachment.ps1

@@ -1,25 +1,6 @@
 function Add-JiraIssueAttachment {
-    <#
-    .SYNOPSIS
-       Adds a file attachment to an existing Jira Issue
-    .DESCRIPTION
-       This function adds an Attachment to an existing issue in JIRA.
-    .EXAMPLE
-       Add-JiraIssueAttachment -FilePath "Test comment" -Issue "TEST-001"
-       This example adds a simple comment to the issue TEST-001.
-    .EXAMPLE
-       Get-JiraIssue "TEST-002" | Add-JiraIssueAttachment -FilePath "Test comment from PowerShell"
-       This example illustrates pipeline use from Get-JiraIssue to Add-JiraIssueAttachment.
-    .INPUTS
-       This function can accept JiraPS.Issue objects via pipeline.
-    .OUTPUTS
-       This function outputs the results of the attachment add.
-    .NOTES
-       This function requires either the -Credential parameter to be passed or a persistent JIRA session. See New-JiraSession for more details.  If neither are supplied, this function will run with anonymous access to JIRA.
-    #>
     [CmdletBinding( SupportsShouldProcess )]
     param(
-        # Issue to which to attach the file
         [Parameter( Mandatory )]
         [ValidateNotNullOrEmpty()]
         [ValidateScript(
@@ -51,7 +32,6 @@ function Add-JiraIssueAttachment {
           Once we have custom classes, this can also accept ValueFromPipeline
         #>
 
-        # Path of the file to upload and attach
         [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )]
         [ValidateScript(
             {
@@ -74,12 +54,9 @@ function Add-JiraIssueAttachment {
         [String[]]
         $FilePath,
 
-        # Credentials to use to connect to JIRA.
-        # If not specified, this function will use anonymous access.
         [PSCredential]
         $Credential,
 
-        # Whether output should be provided after invoking this function
         [Switch]
         $PassThru
     )

JiraPS/Public/Add-JiraIssueComment.ps1

@@ -1,38 +1,11 @@
 function Add-JiraIssueComment {
-    <#
-    .SYNOPSIS
-       Adds a comment to an existing JIRA issue
-    .DESCRIPTION
-       This function adds a comment to an existing issue in JIRA. You can optionally set the visibility of the comment (All Users, Developers, or Administrators).
-    .EXAMPLE
-       Add-JiraIssueComment -Comment "Test comment" -Issue "TEST-001"
-       This example adds a simple comment to the issue TEST-001.
-    .EXAMPLE
-       Get-JiraIssue "TEST-002" | Add-JiraIssueComment "Test comment from PowerShell"
-       This example illustrates pipeline use from Get-JiraIssue to Add-JiraIssueComment.
-    .EXAMPLE
-       Get-JiraIssue -Query 'project = "TEST" AND created >= -5d' | % { Add-JiraIssueComment "This issue has been cancelled per Vice President's orders." }
-       This example illustrates commenting on all projects which match a given JQL query. It would be best to validate the query first to make sure the query returns the expected issues!
-    .EXAMPLE
-       $comment = Get-Process | Format-Jira
-       Add-JiraIssueComment $c -Issue TEST-003
-       This example illustrates adding a comment based on other logic to a JIRA issue.  Note the use of Format-Jira to convert the output of Get-Process into a format that is easily read by users.
-    .INPUTS
-       This function can accept JiraPS.Issue objects via pipeline.
-    .OUTPUTS
-       This function outputs the JiraPS.Comment object created.
-    .NOTES
-       This function requires either the -Credential parameter to be passed or a persistent JIRA session. See New-JiraSession for more details.  If neither are supplied, this function will run with anonymous access to JIRA.
-    #>
     [CmdletBinding( SupportsShouldProcess )]
     param(
-        # Comment that should be added to JIRA.
         [Parameter( Mandatory )]
         [ValidateNotNullOrEmpty()]
         [String]
         $Comment,
 
-        # Issue that should be commented upon.
         [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )]
         [ValidateNotNullOrEmpty()]
         [ValidateScript(
@@ -60,13 +33,10 @@ function Add-JiraIssueComment {
         [Object]
         $Issue,
 
-        # Visibility of the comment - should it be publicly visible, viewable to only developers, or only administrators?
         [ValidateSet('All Users', 'Developers', 'Administrators')]
         [String]
         $VisibleRole = 'All Users',
 
-        # Credentials to use to connect to JIRA.
-        # If not specified, this function will use anonymous access.
         [PSCredential]
         $Credential
     )

JiraPS/Public/Add-JiraIssueLink.ps1

@@ -1,23 +1,6 @@
 function Add-JiraIssueLink {
-    <#
-    .SYNOPSIS
-        Adds a link between two Issues on Jira
-    .DESCRIPTION
-        Creates a new link of the specified type between two Issue.
-    .EXAMPLE
-        $_issueLink = [PSCustomObject]@{
-            outwardIssue = [PSCustomObject]@{key = "TEST-10"}
-            type = [PSCustomObject]@{name = "Composition"}
-        }
-        Add-JiraIssueLink -Issue TEST-01 -IssueLink $_issueLink
-        Creates a link "is part of" between TEST-01 and TEST-10
-    .INPUTS
-        [JiraPS.Issue[]] The JIRA issue that should be linked
-        [JiraPS.IssueLink[]] The JIRA issue link that should be used
-    #>
     [CmdletBinding( SupportsShouldProcess )]
     param(
-        # Issue key or JiraPS.Issue object returned from Get-JiraIssue
         [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )]
         [ValidateNotNullOrEmpty()]
         [ValidateScript(
@@ -45,7 +28,6 @@ function Add-JiraIssueLink {
         [Object[]]
         $Issue,
 
-        # Issue Link to be created.
         [Parameter( Mandatory )]
         [ValidateScript(
             {
@@ -75,12 +57,9 @@ function Add-JiraIssueLink {
         [Object[]]
         $IssueLink,
 
-        # Write a comment to the issue
         [String]
         $Comment,
 
-        # Credentials to use to connect to JIRA.
-        # If not specified, this function will use anonymous access.
         [PSCredential]
         $Credential
     )

JiraPS/Public/Add-JiraIssueWatcher.ps1

@@ -1,28 +1,6 @@
 function Add-JiraIssueWatcher {
-    <#
-    .SYNOPSIS
-       Adds a watcher to an existing JIRA issue
-    .DESCRIPTION
-       This function adds a watcher to an existing issue in JIRA.
-    .EXAMPLE
-       Add-JiraIssueWatcher -Watcher "fred" -Issue "TEST-001"
-       This example adds a watcher to the issue TEST-001.
-    .EXAMPLE
-       Get-JiraIssue "TEST-002" | Add-JiraIssueWatcher "fred"
-       This example illustrates pipeline use from Get-JiraIssue to Add-JiraIssueWatcher.
-    .EXAMPLE
-       Get-JiraIssue -Query 'project = "TEST" AND created >= -5d' | % { Add-JiraIssueWatcher "fred" }
-       This example illustrates adding watcher on all projects which match a given JQL query. It would be best to validate the query first to make sure the query returns the expected issues!
-    .INPUTS
-       This function can accept JiraPS.Issue objects via pipeline.
-    .OUTPUTS
-       This function does not provide output.
-    .NOTES
-       This function requires either the -Credential parameter to be passed or a persistent JIRA session. See New-JiraSession for more details.  If neither are supplied, this function will run with anonymous access to JIRA.
-    #>
     [CmdletBinding( SupportsShouldProcess )]
     param(
-        # Watcher that should be added to JIRA
         [Parameter( Mandatory )]
         [String[]]
         $Watcher,
@@ -31,7 +9,6 @@
           Once we have custom classes, this can also accept ValueFromPipeline
         #>
 
-        # Issue that should be watched
         [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )]
         [ValidateNotNullOrEmpty()]
         [ValidateScript(
@@ -59,8 +36,6 @@
         [Object]
         $Issue,
 
-        # Credentials to use to connect to JIRA.
-        # If not specified, this function will use anonymous access.
         [PSCredential]
         $Credential
     )

JiraPS/Public/Add-JiraIssueWorklog.ps1

@@ -1,38 +1,11 @@
 function Add-JiraIssueWorklog {
-    <#
-    .SYNOPSIS
-       Adds a worklog item to an existing JIRA issue
-    .DESCRIPTION
-       This function adds a worklog item to an existing issue in JIRA. You can optionally set the visibility of the item (All Users, Developers, or Administrators).
-    .EXAMPLE
-       Add-JiraIssueWorklog -Comment "Test comment" -Issue "TEST-001" -TimeSpent 60 -DateStarted (Get-Date)
-       This example adds a simple worklog item to the issue TEST-001.
-    .EXAMPLE
-       Get-JiraIssue "TEST-002" | Add-JiraIssueWorklog "Test worklog item from PowerShell" -TimeSpent 60 -DateStarted (Get-Date)
-       This example illustrates pipeline use from Get-JiraIssue to Add-JiraIssueWorklog.
-    .EXAMPLE
-       Get-JiraIssue -Query 'project = "TEST" AND created >= -5d' | % { Add-JiraIssueWorklog "This issue has been cancelled per Vice President's orders." -TimeSpent 60 -DateStarted (Get-Date)}
-       This example illustrates logging work on all projects which match a given JQL query. It would be best to validate the query first to make sure the query returns the expected issues!
-    .EXAMPLE
-       $comment = Get-Process | Format-Jira
-       Add-JiraIssueWorklog $c -Issue TEST-003 -TimeSpent 60 -DateStarted (Get-Date)
-       This example illustrates adding a comment based on other logic to a JIRA issue.  Note the use of Format-Jira to convert the output of Get-Process into a format that is easily read by users.
-    .INPUTS
-       This function can accept JiraPS.Issue objects via pipeline.
-    .OUTPUTS
-       This function outputs the JiraPS.Worklogitem object created.
-    .NOTES
-       This function requires either the -Credential parameter to be passed or a persistent JIRA session. See New-JiraSession for more details.  If neither are supplied, this function will run with anonymous access to JIRA.
-    #>
     [CmdletBinding( SupportsShouldProcess )]
     param(
-        # Worklog item that should be added to JIRA
         [Parameter( Mandatory )]
         [ValidateNotNullOrEmpty()]
         [String]
         $Comment,
 
-        # Issue to receive the new worklog item
         [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )]
         [ValidateNotNullOrEmpty()]
         [ValidateScript(
@@ -60,23 +33,18 @@ function Add-JiraIssueWorklog {
         [Object]
         $Issue,
 
-        # Time spent to be logged
         [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )]
         [TimeSpan]
         $TimeSpent,
 
-        # Date/time started to be logged
         [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )]
         [DateTime]
         $DateStarted,
 
-        # Visibility of the comment - should it be publicly visible, viewable to only developers, or only administrators?
         [ValidateSet('All Users', 'Developers', 'Administrators')]
         [String]
         $VisibleRole = 'All Users',
 
-        # Credentials to use to connect to JIRA.
-        # If not specified, this function will use anonymous access.
         [PSCredential]
         $Credential
     )

JiraPS/Public/Format-Jira.ps1

@@ -1,36 +1,12 @@
 function Format-Jira {
-    <#
-    .SYNOPSIS
-       Converts an object into a table formatted according to JIRA's markdown syntax
-    .DESCRIPTION
-       This function converts a PowerShell object into a table using JIRA's markdown syntax. This can then be added to a JIRA issue description or comment.
-
-       Like the native Format-* cmdlets, this is a destructive operation, so as always, remember to "filter left, format right!"
-    .EXAMPLE
-       Get-Process | Format-Jira | Add-JiraIssueComment -Issue TEST-001
-       This example illustrates converting the output from Get-Process into a JIRA table, which is then added as a comment to issue TEST-001.
-    .EXAMPLE
-       Get-Process chrome | Format-Jira Name,Id,VM
-       This example obtains all Google Chrome processes, then creates a JIRA table with only the Name,ID, and VM properties of each object.
-    .INPUTS
-       [System.Object[]] - accepts any Object via pipeline
-    .OUTPUTS
-       [System.String]
-    .NOTES
-       This is a destructive operation, since it permanently reduces InputObjects to Strings.  Remember to "filter left, format right."
-    #>
     [CmdletBinding()]
     [OutputType([System.String])]
     param(
-        # Object to format.
         [Parameter( Mandatory, ValueFromPipeline, ValueFromRemainingArguments )]
         [ValidateNotNull()]
         [PSObject[]]
         $InputObject,
 
-        # List of properties to display. If omitted, only the default properties will be shown.
-        #
-        # To display all properties, use -Property *.
         [Object[]]
         $Property
     )