Merge pull request #335 from X-Guardian/WikiPages-Update

Publish-WikiContent: Add Wiki Sidebar, Footer and WikiSource File Copy

Author: PlagueHO

CHANGELOG.md

@@ -55,9 +55,17 @@
       the resource file.
     - There should be no additional localized string keys in the resource
       file that do not exist in the en-US resource file.
-- Added `Publish-WikiContent` helper function to publish auto-generated
-  Wiki files to the relevant DSC resource GitHub Wiki
-  ([issue #142](https://github.com/PowerShell/DscResource.Tests/issues/142)).
+- Added `Publish-WikiContent` helper function to publish auto-generated Wiki files
+  to the relevant DSC resource GitHub Wiki with sidebar, footer and WikiSource file
+  copying ([issue #142](https://github.com/PowerShell/DscResource.Tests/issues/142),
+  [issue #227](https://github.com/PowerShell/DscResource.Tests/issues/227) and
+  [issue #228](https://github.com/PowerShell/DscResource.Tests/issues/228)).
+- Update New-DscResourcePowerShellHelp to output the PowerShell help files to
+  to the relevant DSC resource GitHub Wiki ([issue #142](https://github.com/PowerShell/DscResource.Tests/issues/142)).
+- Update New-DscResourcePowerShellHelp to optionally output the PowerShell help files to
+  the resource specific path and fix the example processing.
+- Added processing to `Test-PublishMetaData` for the InvalidGUID error from Test-ScriptFileInfo
+  ([issue #330](https://github.com/PowerShell/DscResource.Tests/issues/330)).
 - Update New-DscResourcePowerShellHelp to optionally output the PowerShell
   help files to the resource specific path and fix the example processing.
   - The files are now outputted as UTF-8 (ASCII).

DscResource.DocumentationHelper/WikiPages.psm1

@@ -303,18 +303,27 @@ function Get-DscResourceWikiExampleContent
 
 <#
     .SYNOPSIS
-        Publishes the Wiki Content from an AppVeyor job artifact.
+        Publishes the Wiki Content from a module and AppVeyor job artifact.
 
     .DESCRIPTION
-        This function adds the content pages from the Wiki Content artifact of a specified
-        AppVeyor job to the Wiki of a specified GitHub repository.
+        This function publishes the content pages from the Wiki Content artifact
+        of a specified AppVeyor job along with any additional files stored in the
+        'WikiSource' directory of the repository and an auto-generated sidebar file
+        containing links to all the markdown files to the Wiki of a specified GitHub
+        repository.
 
     .PARAMETER RepoName
         The name of the Github Repo, in the format <account>/<repo>.
 
     .PARAMETER JobId
         The AppVeyor job id that contains the wiki artifact to publish.
 
+    .PARAMETER MainModulePath
+        The path of the DSC Resource Module.
+
+    .PARAMETER WikiSourceFolder
+        The name of the folder in the DSC Resource Module that contains any Wiki source files.
+
     .PARAMETER ResourceModuleName
         The name of the Dsc Resource Module.
 
@@ -332,9 +341,9 @@ function Get-DscResourceWikiExampleContent
 
     .EXAMPLE
         Publish-WikiContent -RepoName 'PowerShell/xActiveDirectory' -JobId 'imy2wgp1ylo9bcpb' -ResourceModuleName 'xActiveDirectory' `
-                            -BuildVersion 'v1.0.0'
+                            -MainModulePath 'C:\ModulePath' -BuildVersion 'v1.0.0'
 
-        Adds the Content pages from the AppVeyor Job artifact to the Wiki for the specified GitHub repository.
+        Adds the Content pages from the AppVeyor Job artifact and module path to the Wiki for the specified GitHub repository.
 
     .NOTES
         Appveyor - Push to remote Git repository from a build: https://www.appveyor.com/docs/how-to/git-push/
@@ -352,6 +361,16 @@ function Publish-WikiContent
         [System.String]
         $JobId = $env:APPVEYOR_JOB_ID,
 
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $MainModulePath = $env:APPVEYOR_BUILD_FOLDER,
+
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $WikiSourceFolder = 'WikiSource',
+
         [Parameter()]
         [System.String]
         $ResourceModuleName = (($env:APPVEYOR_REPO_NAME -split '/')[1]),
@@ -432,6 +451,10 @@ function Publish-WikiContent
         Expand-Archive -Path $wikiContentArtifactPath -DestinationPath $path -Force
         Remove-Item -Path $wikiContentArtifactPath
 
+        Set-WikiSidebar -ResourceModuleName $ResourceModuleName -Path $path
+        Set-WikiFooter -ResourceModuleName $ResourceModuleName -Path $path
+        Copy-WikiFile -MainModulePath $MainModulePath -Path $path -WikiSourceFolder $WikiSourceFolder
+
         Push-Location
         Set-Location -Path $path
 
@@ -478,7 +501,7 @@ function Invoke-Git
     [CmdletBinding()]
     param
     (
-        [parameter(ValueFromRemainingArguments = $true)]
+        [Parameter(ValueFromRemainingArguments = $true)]
         [System.String[]]
         $Arguments
     )
@@ -541,4 +564,138 @@ function New-TempFolder
     return $path
 }
 
+<#
+    .SYNOPSIS
+        Creates the Wiki side bar file from the list of markdown files in the path.
+
+    .PARAMETER ResourceModuleName
+        The name of the resource module.
+
+    .PARAMETER Path
+        The path of the Wiki page files.
+
+    .EXAMPLE
+        Set-WikiSidebar -ResourceModuleName $ResourceModuleName -Path $path
+
+        Creates the Wiki side bar from the list of markdown files in the path.
+#>
+function Set-WikiSidebar
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $ResourceModuleName,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Path
+    )
+
+    $wikiSideBarFileBaseName = '_Sidebar.md'
+    $wikiSideBarFileFullName = Join-Path -Path $path -ChildPath $wikiSideBarFileBaseName
+
+    Write-Verbose -Message ($localizedData.GenerateWikiSidebarMessage -f $wikiSideBarFileBaseName)
+    $WikiSidebar = @(
+        "# $ResourceModuleName Module"
+        ' '
+    )
+
+    $wikiFiles = Get-ChildItem -Path $Path -Filter '*.md'
+
+    foreach ($file in $wikiFiles)
+    {
+        $wikiSidebar += "- [$($file.BaseName)]($($file.BaseName))"
+    }
+
+    Out-File -InputObject $wikiSideBar -FilePath $wikiSideBarFileFullName -Encoding ASCII
+}
+
+<#
+    .SYNOPSIS
+        Creates the Wiki footer file if one does not already exist.
+
+    .PARAMETER Path
+        The path for the Wiki footer file.
+
+    .EXAMPLE
+        Set-WikiFooter -Path $path
+
+        Creates the Wiki footer.
+#>
+function Set-WikiFooter
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $ResourceModuleName,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Path
+    )
+
+    $wikiFooterFileBaseName = '_Footer.md'
+    $wikiFooterFileFullName = Join-Path -Path $path -ChildPath $wikiFooterFileBaseName
+
+    if (-not (Test-Path -Path $wikiFooterFileFullName))
+    {
+        Write-Verbose -Message ($localizedData.GenerateWikiFooterMessage -f $wikiFooterFileBaseName)
+        $wikiFooter = @()
+
+        Out-File -InputObject $wikiFooter -FilePath $wikiFooterFileFullName -Encoding ASCII
+    }
+}
+
+<#
+    .SYNOPSIS
+        Copies any Wiki files from the module into the Wiki overwriting any existing files.
+
+    .PARAMETER MainModulePath
+        The path of the module.
+
+    .PARAMETER Path
+        The destination path for the Wiki files.
+
+    .PARAMETER WikiSourceFolder
+        The name of the folder that contains the source Wiki files.
+
+    .EXAMPLE
+        Copy-WikiFile -MainModulePath $MainModulePath -Path $path -WikiSourcePath $wikiSourcePath
+
+        Copies any Wiki files from the module into the Wiki.
+#>
+function Copy-WikiFile
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $MainModulePath,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Path,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $WikiSourceFolder
+    )
+
+    $wikiSourcePath = Join-Path -Path $MainModulePath -ChildPath $WikiSourceFolder
+    Write-Verbose -Message ($localizedData.CopyWikiFilesMessage -f $wikiSourcePath)
+
+    $wikiFiles = Get-ChildItem -Path $wikiSourcePath
+    foreach ($file in $wikiFiles)
+
+    {
+        Write-Verbose -Message ($localizedData.CopyFileMessage -f $file.name)
+        Copy-Item -Path $file.fullname -Destination $Path -Force
+    }
+}
+
 Export-ModuleMember -Function New-DscResourceWikiSite, Publish-WikiContent

DscResource.DocumentationHelper/en-US/WikiPages.strings.psd1

@@ -16,4 +16,8 @@ ConvertFrom-StringData @'
     NoWikiContentArtifactError                 = No Wiki Content artifact found in AppVeyor job id '{0}'.
     NewTempFolderCreationError                 = Unable to create a temporary working folder in '{0}'.
     InvokingGitMessage                         = Invoking Git '{0}'.
+    GenerateWikiSidebarMessage                 = Generating Wiki Sidebar '{0}'.
+    GenerateWikiFooterMessage                  = Generating Wiki Footer '{0}'.
+    CopyWikiFilesMessage                       = Copying Wiki files from '{0}'.
+    CopyFileMessage                            = Copying file '{0}' to the Wiki.
 '@

README.md

@@ -813,6 +813,10 @@ To opt-in to this task, change the appveyor.yml to include the opt-in task
 By opting-in to the *PublishWikiContent* task, the test framework will publish the
 contents of a DSC Resource Module Wiki Content artifact to the relevant GitHub Wiki
 repository, but only if it is a 'master' branch build (`$env:APPVEYOR_REPO_BRANCH -eq 'master'`).
+A Wiki Sidebar file will be generated, containing links to all of the markdown
+files in the Wiki, as well as as a Wiki Footer file. Any files contained within the
+`WikiSource` directory of the repository will also be published to the Wiki
+overriding any auto generated files.
 
 > **Note:** It is possible to override the deploy branch in appveyor.yml,
 > e.g. `Invoke-AppVeyorDeployTask -Branch @('dev','my-working-branch')`.