Modules/ActiveDirectoryDsc.Common/Build-Readme.ps1
|
<#
.SYNOPSIS Builds the markdown documentation for the common module. .DESCRIPTION The Build-ReadMe script is used to build the markdown documentation for the common module. this uses functions from the PlatyPS PowerShell Module to build the markdown from the PowerShell comment based help in the module. .EXAMPLE Build-ReadMe .PARAMETER Path Specifies the output path for the function markdown files. .PARAMETER ModulePagePath Specifies the output path for the main module markdown file. .PARAMETER HelpVersion Specifies the version of the help files. .PARAMETER ModuleName Specifies the name of the main module. .PARAMETER CommonModuleName Specifies the name of the common module. .PARAMETER ModuleRootPath Specifies the path of the root of the main module. .PARAMETER StubModulePath Specifies the path of the stub modules. .PARAMETER Description Specifies the description for the common module. .INPUTS None .OUTPUTS System.IO.FileInfo[] #> [CmdletBinding()] param ( [Parameter()] [System.String] $Path = 'docs', [Parameter()] [System.String] $ModulePagePath = 'README.md', [Parameter()] [System.String] $HelpVersion = '1.0.0', [Parameter()] [System.String] $ModuleName = 'ActiveDirectoryDsc', [Parameter()] [System.String] $CommonModuleName = "$($ModuleName).Common", [Parameter()] [System.String] $ModuleRootPath = '..\..\..', [Parameter()] [System.String] $StubModulePath = "$ModuleRootPath\tests\Unit\Stubs", [Parameter()] [System.String] $Description = "The $CommonModuleName module is a PowerShell module that contains a set of functions that are " + ` "common across the $ModuleName Module" ) Function Remove-MetaData { [CmdletBinding()] param ( [Parameter()] [System.String[]] $Content ) $inMetadataBlock = $false $newContent = @() foreach ($line in $Content) { if ($line -eq '---') { if ($inMetadataBlock) { $inMetadataBlock = $false } else { $inMetadataBlock = $true } } else { if (!$inMetadataBlock) { $newContent += $line } } } return $newContent } $ErrorActionPreference = 'Stop' Set-StrictMode -Version 1.0 Write-Verbose -Message "Building the resource module" & "$ModuleRootPath\build.ps1" -Tasks build -Verbose:$false Write-Verbose -Message "Importing the test Stub Modules" $stubModules = Get-ChildItem -Path $StubModulePath -Filter '*.psm1' Import-Module -Name $stubModules.FullName -Verbose:$false -Force Write-Verbose -Message "Force importing the $CommonModuleName module" $moduleVersion = (Get-ChildItem -Path "$ModuleRootPath\output\$ModuleName")[0].Name Import-Module $ModuleRootPath\output\$ModuleName\$moduleVersion\Modules\$CommonModuleName -Verbose:$false -Force Write-Verbose "Adding the PrincipalContext Type" Add-TypeAssembly -AssemblyName 'System.DirectoryServices.AccountManagement' ` -TypeName 'System.DirectoryServices.AccountManagement.PrincipalContext' If (Test-Path -Path $Path) { Write-Verbose -Message "Removing the current $Path directory" Remove-Item -Path $Path -Recurse } Write-Verbose -Message "Creating the new module markdown help files in $Path" New-MarkdownHelp -Module $CommonModuleName -OutputFolder $Path -UseFullTypeName -AlphabeticParamsOrder ` -WithModulePage -ModulePagePath $modulePagePath -HelpVersion $HelpVersion -Force -FwLink 'N/A' Update-MarkdownHelpModule -Path $Path -RefreshModulePage -ModulePagePath $modulePagePath -AlphabeticParamsOrder ` -UseFullTypeName | Out-Null Write-Verbose -Message "Getting contents of $ModulePagePath file" $modulePageContent = Get-Content -Path $ModulePagePath Write-Verbose -Message 'Fixing README Markdown link paths' $modulePageContent = $modulePageContent.Replace('(', '(docs/') Write-Verbose -Message 'Updating README module description' $descriptionMarker = '{{ Fill in the Description }}' $modulePageContent = $modulePageContent.Replace($descriptionMarker, $description) Write-Verbose -Message 'Removing README Metadata' $newModulePageContent = Remove-MetaData -Content $modulePageContent Write-Verbose -Message "Writing updated $ModulePagePath file" $newModulePageContent | Out-File -FilePath $ModulePagePath -Encoding ascii Write-Verbose -Message 'Removing Metadata from function markdown files' $functionMdFiles = Get-ChildItem -Path $Path -Filter '*.md' foreach ($functionMdFile in $functionMdFiles) { $functionMdFileContent = Get-Content -Path $functionMdFile.FullName $newFunctionMdFileContent = Remove-MetaData -Content $functionMdFileContent $newFunctionMdFileContent | Out-File -FilePath $functionMdFile.FullName -Encoding ascii } |