tasks/documentation.tasks.ps1

# <copyright file="documentation.tasks.ps1" company="Endjin Limited">
# Copyright (c) Endjin Limited. All rights reserved.
# </copyright>

. $PSScriptRoot/documentation.properties.ps1

# Synopsis: Ensures the required PlatyPS module is available
task EnsurePlatyPSModule -If { !$SkipGeneratePSMarkdownDocs } -Before setupModules {

    if (!$RequiredPowerShellModules.ContainsKey('Microsoft.PowerShell.PlatyPS')) {
        $script:RequiredPowerShellModules += @{
            'Microsoft.PowerShell.PlatyPS' = @{
                version = '[1.0,2.0)'
                repository = 'PSGallery'
            }
        }
    }
}

# Synopsis: Ensures the markdown documentation output path exists
task EnsurePSMarkdownDocsOutputPath -If { !$SkipGeneratePSMarkdownDocs } {

    # Support dynamic evaluation of PSMarkdownDocsOutputPath
    $script:PSMarkdownDocsOutputPath = Resolve-Value $PSMarkdownDocsOutputPath

    if (!(Test-Path $PSMarkdownDocsOutputPath)) {
        Write-Build White "Creating PS markdown documentation folder: $PSMarkdownDocsOutputPath"
        New-Item -ItemType Directory $PSMarkdownDocsOutputPath -Force | Out-Null
    }
}

# Synopsis: Uses PlatyPS to generate the markdown help documentation from the module's
# comment-based help. Comment-based-help-derived sections (synopsis, description, parameter
# descriptions, examples) are regenerated in full so that the output is deterministic and does
# not accumulate duplicated content across builds; hand-authored sections in the existing
# markdown (OUTPUTS descriptions, RELATED LINKS, ALIASES) are preserved. Tracked files are only
# rewritten when their help content actually changes.
task GeneratePSMarkdownDocs `
    -If { !$SkipGeneratePSMarkdownDocs } `
    -After BuildCore `
    -Jobs GitVersion,EnsurePlatyPSModule,EnsurePSMarkdownDocsOutputPath,{

    foreach ($module in $PowerShellModulesToPublish) {

        $moduleName = Split-Path -LeafBase $module.ModulePath
        Write-Build White "Generating markdown help documentation: $moduleName"

        # Ensure latest version of module is imported
        Import-Module $module.ModulePath -Force

        # By default PlatyPS nests output under a module-name sub-folder. Consumers with a
        # single module per repo often don't want that extra level - honour that here.
        if ($PSMarkdownDocsFlattenOutputPath) {
            $targetPath = $PSMarkdownDocsOutputPath
        }
        else {
            $targetPath = Join-Path $PSMarkdownDocsOutputPath $moduleName
        }

        $commandHelp = _Get-ReconciledPSCommandHelp -ModuleName $moduleName -ExistingDocsPath $targetPath -Locale $PSMarkdownDocsLocale

        # Export into a temporary location and then reconcile against the tracked files, so
        # that the final layout is controlled here and unchanged help doesn't churn the tree.
        $tempOutputFolder = Join-Path ([System.IO.Path]::GetTempPath()) ("zf-psdocs-" + [Guid]::NewGuid().ToString('N'))
        New-Item -ItemType Directory -Path $tempOutputFolder -Force | Out-Null

        try {
            $commandHelp | Export-MarkdownCommandHelp -OutputFolder $tempOutputFolder -Force | Out-Null

            if ($PSMarkdownDocsIncludeModulePage) {
                New-MarkdownModuleFile -CommandHelp $commandHelp `
                                       -OutputFolder $tempOutputFolder `
                                       -HelpVersion $Gitversion.AssemblySemVer `
                                       -Locale $PSMarkdownDocsLocale `
                                       -Force `
                                       -WarningAction SilentlyContinue | Out-Null
            }

            $result = _Sync-GeneratedPSMarkdownDoc -GeneratedPath (Join-Path $tempOutputFolder $moduleName) -TargetPath $targetPath

            if ($result.New) {
                Write-Build White "New files:`n`t$($result.New -join "`n`t")"
            }
            if ($result.Updated) {
                Write-Build White "Updated files:`n`t$($result.Updated -join "`n`t")"
            }
            if (!$result.New -and !$result.Updated) {
                Write-Build Green "Markdown help documentation is already up to date"
            }
        }
        finally {
            Remove-Item -LiteralPath $tempOutputFolder -Recurse -Force -ErrorAction SilentlyContinue
        }
    }
}

# Synopsis: Runs linting against markdown documentation (e.g. to ensure no generated placeholder text)
task RunPSMarkdownDocsLinting `
    -If { !$SkipGeneratePSMarkdownDocs } `
    -After GeneratePSMarkdownDocs `
    -Jobs EnsurePSMarkdownDocsOutputPath,{

    $noPlaceholderText = $true
    Measure-PlatyPSMarkdown -Path (Join-Path $PSMarkdownDocsOutputPath '*.md') |
        Where-Object { $_.MarkdownContent.MarkdownLines -imatch '\{\{ .* \}\}' } |
        ForEach-Object {
            Write-Build Red "[PlaceholdersDetected] File '$($_.FilePath.Replace("$here\",''))' contains generated documentation placeholders"
            $noPlaceholderText = $false
        }

    if (!$noPlaceholderText -and $PSMarkdownDocsRequireLinting) {
        throw "PowerShell markdown documentation linting failed - review previous errors"
    }
    elseif (!$noPlaceholderText) {
        Write-Warning "PowerShell markdown documentation linting failed - warn-only mode)"
    }
    else {
        Write-Build Green "PowerShell markdown documentation linting successful"
    }
}