Skip to content
This repository was archived by the owner on Feb 24, 2021. It is now read-only.

Commit 5d468e3

Browse files
authored
Merge pull request #335 from X-Guardian/WikiPages-Update
Publish-WikiContent: Add Wiki Sidebar, Footer and WikiSource File Copy
2 parents 6c6cbb3 + b378b26 commit 5d468e3

File tree

5 files changed

+339
-11
lines changed

5 files changed

+339
-11
lines changed

CHANGELOG.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,9 +55,17 @@
5555
the resource file.
5656
- There should be no additional localized string keys in the resource
5757
file that do not exist in the en-US resource file.
58-
- Added `Publish-WikiContent` helper function to publish auto-generated
59-
Wiki files to the relevant DSC resource GitHub Wiki
60-
([issue #142](https://github.com/PowerShell/DscResource.Tests/issues/142)).
58+
- Added `Publish-WikiContent` helper function to publish auto-generated Wiki files
59+
to the relevant DSC resource GitHub Wiki with sidebar, footer and WikiSource file
60+
copying ([issue #142](https://github.com/PowerShell/DscResource.Tests/issues/142),
61+
[issue #227](https://github.com/PowerShell/DscResource.Tests/issues/227) and
62+
[issue #228](https://github.com/PowerShell/DscResource.Tests/issues/228)).
63+
- Update New-DscResourcePowerShellHelp to output the PowerShell help files to
64+
to the relevant DSC resource GitHub Wiki ([issue #142](https://github.com/PowerShell/DscResource.Tests/issues/142)).
65+
- Update New-DscResourcePowerShellHelp to optionally output the PowerShell help files to
66+
the resource specific path and fix the example processing.
67+
- Added processing to `Test-PublishMetaData` for the InvalidGUID error from Test-ScriptFileInfo
68+
([issue #330](https://github.com/PowerShell/DscResource.Tests/issues/330)).
6169
- Update New-DscResourcePowerShellHelp to optionally output the PowerShell
6270
help files to the resource specific path and fix the example processing.
6371
- The files are now outputted as UTF-8 (ASCII).

DscResource.DocumentationHelper/WikiPages.psm1

Lines changed: 163 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -303,18 +303,27 @@ function Get-DscResourceWikiExampleContent
303303

304304
<#
305305
.SYNOPSIS
306-
Publishes the Wiki Content from an AppVeyor job artifact.
306+
Publishes the Wiki Content from a module and AppVeyor job artifact.
307307
308308
.DESCRIPTION
309-
This function adds the content pages from the Wiki Content artifact of a specified
310-
AppVeyor job to the Wiki of a specified GitHub repository.
309+
This function publishes the content pages from the Wiki Content artifact
310+
of a specified AppVeyor job along with any additional files stored in the
311+
'WikiSource' directory of the repository and an auto-generated sidebar file
312+
containing links to all the markdown files to the Wiki of a specified GitHub
313+
repository.
311314
312315
.PARAMETER RepoName
313316
The name of the Github Repo, in the format <account>/<repo>.
314317
315318
.PARAMETER JobId
316319
The AppVeyor job id that contains the wiki artifact to publish.
317320
321+
.PARAMETER MainModulePath
322+
The path of the DSC Resource Module.
323+
324+
.PARAMETER WikiSourceFolder
325+
The name of the folder in the DSC Resource Module that contains any Wiki source files.
326+
318327
.PARAMETER ResourceModuleName
319328
The name of the Dsc Resource Module.
320329
@@ -332,9 +341,9 @@ function Get-DscResourceWikiExampleContent
332341
333342
.EXAMPLE
334343
Publish-WikiContent -RepoName 'PowerShell/xActiveDirectory' -JobId 'imy2wgp1ylo9bcpb' -ResourceModuleName 'xActiveDirectory' `
335-
-BuildVersion 'v1.0.0'
344+
-MainModulePath 'C:\ModulePath' -BuildVersion 'v1.0.0'
336345
337-
Adds the Content pages from the AppVeyor Job artifact to the Wiki for the specified GitHub repository.
346+
Adds the Content pages from the AppVeyor Job artifact and module path to the Wiki for the specified GitHub repository.
338347
339348
.NOTES
340349
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
352361
[System.String]
353362
$JobId = $env:APPVEYOR_JOB_ID,
354363

364+
[Parameter()]
365+
[ValidateNotNullOrEmpty()]
366+
[System.String]
367+
$MainModulePath = $env:APPVEYOR_BUILD_FOLDER,
368+
369+
[Parameter()]
370+
[ValidateNotNullOrEmpty()]
371+
[System.String]
372+
$WikiSourceFolder = 'WikiSource',
373+
355374
[Parameter()]
356375
[System.String]
357376
$ResourceModuleName = (($env:APPVEYOR_REPO_NAME -split '/')[1]),
@@ -432,6 +451,10 @@ function Publish-WikiContent
432451
Expand-Archive -Path $wikiContentArtifactPath -DestinationPath $path -Force
433452
Remove-Item -Path $wikiContentArtifactPath
434453

454+
Set-WikiSidebar -ResourceModuleName $ResourceModuleName -Path $path
455+
Set-WikiFooter -ResourceModuleName $ResourceModuleName -Path $path
456+
Copy-WikiFile -MainModulePath $MainModulePath -Path $path -WikiSourceFolder $WikiSourceFolder
457+
435458
Push-Location
436459
Set-Location -Path $path
437460

@@ -478,7 +501,7 @@ function Invoke-Git
478501
[CmdletBinding()]
479502
param
480503
(
481-
[parameter(ValueFromRemainingArguments = $true)]
504+
[Parameter(ValueFromRemainingArguments = $true)]
482505
[System.String[]]
483506
$Arguments
484507
)
@@ -541,4 +564,138 @@ function New-TempFolder
541564
return $path
542565
}
543566

567+
<#
568+
.SYNOPSIS
569+
Creates the Wiki side bar file from the list of markdown files in the path.
570+
571+
.PARAMETER ResourceModuleName
572+
The name of the resource module.
573+
574+
.PARAMETER Path
575+
The path of the Wiki page files.
576+
577+
.EXAMPLE
578+
Set-WikiSidebar -ResourceModuleName $ResourceModuleName -Path $path
579+
580+
Creates the Wiki side bar from the list of markdown files in the path.
581+
#>
582+
function Set-WikiSidebar
583+
{
584+
[CmdletBinding()]
585+
param
586+
(
587+
[Parameter(Mandatory = $true)]
588+
[System.String]
589+
$ResourceModuleName,
590+
591+
[Parameter(Mandatory = $true)]
592+
[System.String]
593+
$Path
594+
)
595+
596+
$wikiSideBarFileBaseName = '_Sidebar.md'
597+
$wikiSideBarFileFullName = Join-Path -Path $path -ChildPath $wikiSideBarFileBaseName
598+
599+
Write-Verbose -Message ($localizedData.GenerateWikiSidebarMessage -f $wikiSideBarFileBaseName)
600+
$WikiSidebar = @(
601+
"# $ResourceModuleName Module"
602+
' '
603+
)
604+
605+
$wikiFiles = Get-ChildItem -Path $Path -Filter '*.md'
606+
607+
foreach ($file in $wikiFiles)
608+
{
609+
$wikiSidebar += "- [$($file.BaseName)]($($file.BaseName))"
610+
}
611+
612+
Out-File -InputObject $wikiSideBar -FilePath $wikiSideBarFileFullName -Encoding ASCII
613+
}
614+
615+
<#
616+
.SYNOPSIS
617+
Creates the Wiki footer file if one does not already exist.
618+
619+
.PARAMETER Path
620+
The path for the Wiki footer file.
621+
622+
.EXAMPLE
623+
Set-WikiFooter -Path $path
624+
625+
Creates the Wiki footer.
626+
#>
627+
function Set-WikiFooter
628+
{
629+
[CmdletBinding()]
630+
param
631+
(
632+
[Parameter(Mandatory = $true)]
633+
[System.String]
634+
$ResourceModuleName,
635+
636+
[Parameter(Mandatory = $true)]
637+
[System.String]
638+
$Path
639+
)
640+
641+
$wikiFooterFileBaseName = '_Footer.md'
642+
$wikiFooterFileFullName = Join-Path -Path $path -ChildPath $wikiFooterFileBaseName
643+
644+
if (-not (Test-Path -Path $wikiFooterFileFullName))
645+
{
646+
Write-Verbose -Message ($localizedData.GenerateWikiFooterMessage -f $wikiFooterFileBaseName)
647+
$wikiFooter = @()
648+
649+
Out-File -InputObject $wikiFooter -FilePath $wikiFooterFileFullName -Encoding ASCII
650+
}
651+
}
652+
653+
<#
654+
.SYNOPSIS
655+
Copies any Wiki files from the module into the Wiki overwriting any existing files.
656+
657+
.PARAMETER MainModulePath
658+
The path of the module.
659+
660+
.PARAMETER Path
661+
The destination path for the Wiki files.
662+
663+
.PARAMETER WikiSourceFolder
664+
The name of the folder that contains the source Wiki files.
665+
666+
.EXAMPLE
667+
Copy-WikiFile -MainModulePath $MainModulePath -Path $path -WikiSourcePath $wikiSourcePath
668+
669+
Copies any Wiki files from the module into the Wiki.
670+
#>
671+
function Copy-WikiFile
672+
{
673+
[CmdletBinding()]
674+
param
675+
(
676+
[Parameter(Mandatory = $true)]
677+
[System.String]
678+
$MainModulePath,
679+
680+
[Parameter(Mandatory = $true)]
681+
[System.String]
682+
$Path,
683+
684+
[Parameter(Mandatory = $true)]
685+
[System.String]
686+
$WikiSourceFolder
687+
)
688+
689+
$wikiSourcePath = Join-Path -Path $MainModulePath -ChildPath $WikiSourceFolder
690+
Write-Verbose -Message ($localizedData.CopyWikiFilesMessage -f $wikiSourcePath)
691+
692+
$wikiFiles = Get-ChildItem -Path $wikiSourcePath
693+
foreach ($file in $wikiFiles)
694+
695+
{
696+
Write-Verbose -Message ($localizedData.CopyFileMessage -f $file.name)
697+
Copy-Item -Path $file.fullname -Destination $Path -Force
698+
}
699+
}
700+
544701
Export-ModuleMember -Function New-DscResourceWikiSite, Publish-WikiContent

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,8 @@ ConvertFrom-StringData @'
1616
NoWikiContentArtifactError = No Wiki Content artifact found in AppVeyor job id '{0}'.
1717
NewTempFolderCreationError = Unable to create a temporary working folder in '{0}'.
1818
InvokingGitMessage = Invoking Git '{0}'.
19+
GenerateWikiSidebarMessage = Generating Wiki Sidebar '{0}'.
20+
GenerateWikiFooterMessage = Generating Wiki Footer '{0}'.
21+
CopyWikiFilesMessage = Copying Wiki files from '{0}'.
22+
CopyFileMessage = Copying file '{0}' to the Wiki.
1923
'@

README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -813,6 +813,10 @@ To opt-in to this task, change the appveyor.yml to include the opt-in task
813813
By opting-in to the *PublishWikiContent* task, the test framework will publish the
814814
contents of a DSC Resource Module Wiki Content artifact to the relevant GitHub Wiki
815815
repository, but only if it is a 'master' branch build (`$env:APPVEYOR_REPO_BRANCH -eq 'master'`).
816+
A Wiki Sidebar file will be generated, containing links to all of the markdown
817+
files in the Wiki, as well as as a Wiki Footer file. Any files contained within the
818+
`WikiSource` directory of the repository will also be published to the Wiki
819+
overriding any auto generated files.
816820

817821
> **Note:** It is possible to override the deploy branch in appveyor.yml,
818822
> e.g. `Invoke-AppVeyorDeployTask -Branch @('dev','my-working-branch')`.

0 commit comments

Comments
 (0)