diff --git a/.gitignore b/.gitignore index 1e7cad46..a602f93d 100644 --- a/.gitignore +++ b/.gitignore @@ -23,4 +23,6 @@ Lib/Core/* *.json *.html .claude/* -CLAUDE.MD \ No newline at end of file +CLAUDE.MD +WebsiteArtifacts/ +en-US/ diff --git a/Build/Build-Module.ps1 b/Build/Build-Module.ps1 index 67b9c908..8b1e8fce 100644 --- a/Build/Build-Module.ps1 +++ b/Build/Build-Module.ps1 @@ -70,7 +70,19 @@ # when creating PSD1 use special style without comments and with only required parameters New-ConfigurationFormat -ApplyTo 'DefaultPSD1', 'OnMergePSD1' -PSD1Style 'Minimal' # configuration for documentation, at the same time it enables documentation processing - New-ConfigurationDocumentation -Enable:$false -StartClean -UpdateWhenNew -PathReadme 'Docs\Readme.md' -Path 'Docs' + $documentationConfiguration = @{ + Enable = $true + StartClean = $true + UpdateWhenNew = $true + PathReadme = 'Docs\Readme.md' + Path = 'Docs' + } + + if ((Get-Command New-ConfigurationDocumentation).Parameters.ContainsKey('SyncExternalHelpToProjectRoot')) { + $documentationConfiguration.SyncExternalHelpToProjectRoot = $true + } + + New-ConfigurationDocumentation @documentationConfiguration New-ConfigurationImportModule -ImportSelf @@ -80,7 +92,7 @@ MergeModuleOnBuild = $true MergeFunctionsFromApprovedModules = $true CertificateThumbprint = '483292C9E317AA13B07BB7A96AE9D1A5ED9E7703' - RefreshPSD1Only = $true + RefreshPSD1Only = $env:RefreshPSD1Only -eq 'true' } New-ConfigurationBuild @newConfigurationBuildSplat @@ -93,4 +105,4 @@ # options for publishing to github/psgallery #New-ConfigurationPublish -Type PowerShellGallery -FilePath 'C:\Support\Important\PowerShellGalleryAPI.txt' -Enabled:$true #New-ConfigurationPublish -Type GitHub -FilePath 'C:\Support\Important\GitHubAPI.txt' -UserName 'EvotecIT' -Enabled:$true -} -ExitCode \ No newline at end of file +} -ExitCode diff --git a/Build/Export-WebsiteArtifacts.ps1 b/Build/Export-WebsiteArtifacts.ps1 new file mode 100644 index 00000000..f5b91164 --- /dev/null +++ b/Build/Export-WebsiteArtifacts.ps1 @@ -0,0 +1,123 @@ +[CmdletBinding()] +param( + [switch]$SkipBuild, + [string]$ArtifactsRoot = (Join-Path $PSScriptRoot '..\WebsiteArtifacts') +) + +$ErrorActionPreference = 'Stop' + +$repoRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..')) +$moduleName = 'PSWriteHTML' +$slug = 'pswritehtml' +$helpCandidates = @( + (Join-Path $repoRoot "en-US\$moduleName-help.xml"), + (Join-Path $repoRoot "Artefacts\Unpacked\$moduleName\en-US\$moduleName-help.xml") +) +$examplesSource = Join-Path $repoRoot 'Examples' +$placeholderMarkers = @( + '{{ Fill in the Synopsis }}', + '{{ Fill in the Description }}', + '{{ Add example code here }}', + '{{ Add example description here }}' +) + +function Find-HelpFile { + foreach ($candidate in $helpCandidates) { + if (Test-Path -LiteralPath $candidate -PathType Leaf) { + return [System.IO.Path]::GetFullPath($candidate) + } + } + + return $null +} + +function Test-PlaceholderContent { + param( + [Parameter(Mandatory)] + [string]$Path + ) + + foreach ($marker in $placeholderMarkers) { + $match = Select-String -Path $Path -Pattern ([regex]::Escape($marker)) -SimpleMatch -List -ErrorAction SilentlyContinue + if ($match) { + throw "Placeholder API content detected in '$Path' ($marker)." + } + } +} + +$helpPath = Find-HelpFile +if (-not $helpPath -and -not $SkipBuild) { + $previousRefresh = $env:RefreshPSD1Only + try { + $env:RefreshPSD1Only = 'false' + & (Join-Path $PSScriptRoot 'Build-Module.ps1') + } finally { + if ($null -eq $previousRefresh) { + Remove-Item Env:RefreshPSD1Only -ErrorAction SilentlyContinue + } else { + $env:RefreshPSD1Only = $previousRefresh + } + } + $helpPath = Find-HelpFile +} + +if (-not $helpPath) { + throw "Unable to find $moduleName external help. Run .\Build\Build-Module.ps1 first." +} + +Test-PlaceholderContent -Path $helpPath + +$resolvedArtifactsRoot = [System.IO.Path]::GetFullPath($ArtifactsRoot) +$apiRoot = Join-Path $resolvedArtifactsRoot 'apidocs\powershell' +$examplesTarget = Join-Path $apiRoot 'examples' + +if (Test-Path -LiteralPath $apiRoot) { + Remove-Item -LiteralPath $apiRoot -Recurse -Force +} + +New-Item -ItemType Directory -Path $apiRoot -Force | Out-Null +Copy-Item -LiteralPath $helpPath -Destination (Join-Path $apiRoot "$moduleName-help.xml") -Force + +if (Test-Path -LiteralPath $examplesSource -PathType Container) { + Copy-Item -LiteralPath $examplesSource -Destination $examplesTarget -Recurse -Force +} + +$psd1Path = Join-Path $repoRoot "$moduleName.psd1" +$version = $null +if (Test-Path -LiteralPath $psd1Path -PathType Leaf) { + $version = (Import-PowerShellDataFile -Path $psd1Path).ModuleVersion.ToString() +} + +$commit = (& git -C $repoRoot rev-parse HEAD).Trim() +$manifest = [ordered]@{ + slug = $slug + name = $moduleName + description = 'PSWriteHTML website artifacts for the Evotec multi-project hub.' + mode = 'hub-full' + contentMode = 'hybrid' + status = 'active' + listed = $true + version = $version + generatedAt = (Get-Date).ToString('o') + commit = $commit + links = [ordered]@{ + source = 'https://github.com/EvotecIT/PSWriteHTML' + } + surfaces = [ordered]@{ + docs = $true + apiPowerShell = $true + apiDotNet = $false + examples = $false + } + artifacts = [ordered]@{ + api = 'WebsiteArtifacts/apidocs' + docs = 'Website/content/project-docs' + examples = 'Examples' + } +} + +$manifestPath = Join-Path $resolvedArtifactsRoot 'project-manifest.json' +New-Item -ItemType Directory -Path $resolvedArtifactsRoot -Force | Out-Null +$manifest | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $manifestPath -Encoding UTF8 + +Write-Host "Exported website artifacts -> $resolvedArtifactsRoot" -ForegroundColor Green