BuildDocs.ps1

<#
.SYNOPSIS
    This script builds documentation (manuals, tutorials, release notes) in selected language(s) from the languages.json file and optionally includes API documentation.
.DESCRIPTION
    The script allows the user to build documentation in English or any other available language specified in the languages.json file. It provides options to build documentation in all available languages, run a local website for the documentation, or cancel the operation. If the user chooses to build the documentation, the script also prompts whether API documentation should be included unless API building is explicitly skipped.
.NOTES
    The documentation files are expected to be in Markdown format (.md). The script uses the DocFX tool to build the documentation and optionally includes API documentation. The script generates the API documentation from C# source files using DocFX metadata and can run a local website using the DocFX serve command. This script can also be run from GitHub Actions.
.LINK
    https://github.com/stride3d/stride-docs
.LINK
    https://github.com/stride3d/stride-docs/blob/master/en/languages.json
.LINK
    https://dotnet.github.io/docfx/index.html
.PARAMETER BuildAll
    Switch parameter. If provided, the script will build documentation in all available languages and include API documentation unless SkipApiBuilding is also provided.
.PARAMETER Version
    The Version to build the Docs, the default is the latest version
.PARAMETER SkipApiBuilding
    Switch parameter. If provided, it skips API metadata generation and excludes API documentation from the build.
.PARAMETER SkipPdfBuilding
    Switch parameter. If provided, It skips Pdf generation step.
.EXAMPLE
    .\BuildDocs.ps1 -BuildAll
    In this example, the script will build the documentation in all available languages and include API documentation. Use this in GitHub Actions.
.EXAMPLE
    .\BuildDocs.ps1 -BuildAll -SkipApiBuilding
    In this example, the script will build the documentation in all available languages without generating API documentation. Use this in GitHub Actions when API docs should be skipped.
.EXAMPLE
    .\BuildDocs.ps1
    In this example, the script will prompt the user to select an operation and an optional language. If the user chooses to build the documentation, the script will also ask if they want to include API documentation.
.EXAMPLE
    .\BuildDocs.ps1 -SkipPdfBuilding
#>

param (
    [switch]$BuildAll,
    [switch]$SkipApiBuilding,
    [switch]$SkipPdfBuilding,
    [ArgumentCompleter({
        [OutputType([System.Management.Automation.CompletionResult])]
        param([string] $CommandName,[string] $ParameterName,[string] $WordToComplete,[System.Management.Automation.Language.CommandAst] $CommandAst,[System.Collections.IDictionary] $FakeBoundParameters)
        return (Get-Content $PSScriptRoot\versions.json -Raw -Encoding UTF8 | ConvertFrom-Json).docs | ForEach-Object { $_.url }
    })]
    # The highest version of versions.json, which is the one this branch documents
    $Version = $((Get-Content $PSScriptRoot\versions.json -Raw -Encoding UTF8 | ConvertFrom-Json).docs | ForEach-Object { $_.url } | Sort-Object { [version]$_ } -Descending | Select-Object -First 1)
)

$versionsJson = Get-Content $PSScriptRoot\versions.json -Raw -Encoding UTF8 | ConvertFrom-Json

$Settings = [PSCustomObject]@{
    Version = $Version
    SiteDirectory = "_site/$Version"
    # Sections of en/ that aren't versioned: built from master into /en/, redirected there from every version (see web.config)
    UnversionedSections = @($versionsJson.unversioned)
    UnversionedDirectory = "_site/en"
    # Versions hosted on the website, the release notes link to their own version when it's one of them
    HostedVersions = @($versionsJson.docs | ForEach-Object { $_.url })
    LocalTestHostUrl = "http://localhost:8080/$Version/en/index.html"
    LanguageJsonPath = "en\languages.json"
    LogPath = ".\build.log"
    TempDirectory = "_tmp"
    WebDirectory = "_site"
    IndexFileName = "index.md"
    ManualFolderName = "manual"
    DocsUrl = "https://doc.stride3d.net"
    EngineRepositoryUrl = "https://github.com/stride3d/stride/tree/master"
}

# To Do fix, GitHub references, fix sitemap links to latest/en/

function Read-LanguageConfigurations {
    return Get-Content $Settings.LanguageJsonPath -Encoding UTF8 | ConvertFrom-Json
}

function Get-UserInput {
    Write-Host ""
    Write-Host -ForegroundColor Cyan "Please select an option:"
    Write-Host ""
    Write-Host -ForegroundColor Yellow "  [en] Build English documentation"
    foreach ($lang in $languages) {
        if ($lang.Enabled -and -not $lang.IsPrimary) {
            Write-Host -ForegroundColor Yellow "  [$($lang.Code)] Build $($lang.Name) documentation"
        }
    }
    Write-Host -ForegroundColor Yellow "  [all] Build documentation in all available languages"
    Write-Host -ForegroundColor Yellow "  [r] Run local website"
    Write-Host -ForegroundColor Yellow "  [c] Cancel"
    Write-Host ""
    $validOptions = @('all', 'r', 'c') + $($languages | Select-Object -ExpandProperty Code)

    while($true)
    {
        $userChoice = Read-Host -Prompt "Your choice"
        if($validOptions -contains $userChoice)
        {
            return $userChoice.ToLower()
        }
    }
    Write-Error "No valid Choice was given."
}

function Ask-IncludeAPI {
    Write-Host ""
    Write-Host -ForegroundColor Cyan "Do you want to include API?"
    Write-Host ""
    Write-Host -ForegroundColor Yellow "  [Y] Yes or ENTER"
    Write-Host -ForegroundColor Yellow "  [N] No"
    Write-Host ""

    $answer = Read-Host -Prompt "Your choice [Y, N, or ENTER (default is Y)]"

    return ($answer -ieq "y" -or $answer -eq "")
}

function Ask-UseExistingAPI {
    Write-Host ""
    Write-Host -ForegroundColor Cyan "Do you want to use already generated API metadata?"
    Write-Host ""
    Write-Host -ForegroundColor Yellow "  [Y] Yes or ENTER"
    Write-Host -ForegroundColor Yellow "  [N] No"
    Write-Host ""

    $answer = Read-Host -Prompt "Your choice [Y, N, or ENTER (default is Y)]"

    return ($answer -ieq "y" -or $answer -eq "")
}

function Ask-ReplaceEngineArchitectureDocs {
    Write-Host ""
    Write-Host -ForegroundColor Cyan "Do you want to copy and replace engine architecture docs?"
    Write-Host ""
    Write-Host -ForegroundColor Yellow "  [Y] Yes or ENTER"
    Write-Host -ForegroundColor Yellow "  [N] No"
    Write-Host ""

    $answer = Read-Host -Prompt "Your choice [Y, N, or ENTER (default is Y)]"

    return ($answer -ieq "y" -or $answer -eq "")
}

function Get-RelativePath {
    param (
        [string]$BasePath,
        [string]$Path
    )
    $baseUri = [Uri]((Resolve-Path $BasePath).Path.TrimEnd([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar) + [System.IO.Path]::DirectorySeparatorChar)
    $pathUri = [Uri](Resolve-Path $Path).Path
    return [Uri]::UnescapeDataString($baseUri.MakeRelativeUri($pathUri).ToString())
}
function Copy-ArchitectureDocs {
    Write-Host -ForegroundColor Green "Copying architecture documentation from the main engine repository..."
    $architectureFolder = "en/contributors/engine/architecture"
    $engineDocsFolder = Join-Path $PSScriptRoot "..\stride\docs"

    # Return if the repository isn't available
    if (-not (Test-Path $engineDocsFolder)) {
        Write-Host -ForegroundColor Yellow "Skipping copying architecture documentation, can't find the main engine repository. Make sure the stride directory is located next to stride-docs."
        return
    }

    # Remove old files
    if (Test-Path $architectureFolder) {
        Remove-Item $architectureFolder/* -Recurse -Verbose
    }

    # Copy files
    Get-ChildItem $engineDocsFolder -Force | ForEach-Object {
        Copy-Item $_.FullName (Join-Path $architectureFolder $_.Name) -Recurse -Verbose
    }

    # Post-processing files
    $files = Get-ChildItem $architectureFolder -Recurse -Force
    foreach ($file in $files) {
        $relativePath = Get-RelativePath $architectureFolder $file.FullName

        # Replacing content
        if (!$file.PSIsContainer) {
            $relativePathSlashes = ([regex]::Matches($relativePath, "/" )).count
            $wrongRelative = "]($("../" * $relativePathSlashes)"

            # Go over all lines in the file
            $content = Get-Content $file.FullName
            for ($i = 0; $i -lt $content.Length; $i++) {
                # Look for links
                $linkMatches = [regex]::Matches($content[$i], "\[[^\[\]]*?\]\([^\(\)]*?\)")
                foreach ($match in $linkMatches) {
                    # Replace relative links to files from the repo with non-relative
                    $content[$i] = $content[$i].Replace($wrongRelative, "]($($Settings.EngineRepositoryUrl)/")

                    # Replace links to README.md files with index.md
                    if (!$content[$i].Contains("https://") -and $content[$i].Contains("README")) {
                        $content[$i] = $content[$i].Replace("README", "index")
                    }
                }
            }

            ## Apply changes to content
            $content | Set-Content $file.FullName
        }

        # Rename README.md files to index.md
        if ($file.ToString().ToLower().Contains("readme.md")) {
            $renamedLocation = "$($file.FullName | Split-Path)/index.md"
            Move-Item $file.FullName $renamedLocation
        }
    }

    # Copy root index file
    $sectionIndex = "en/contributors/engine/architecture-index.md"
    if (Test-Path $sectionIndex) {
        Copy-Item $sectionIndex "$architectureFolder/index.md"
    }
}

function Get-ArchitectureDocsTocChildren {


    param ([string]$Directory)

    return @(Get-ChildItem -LiteralPath $Directory -Force |
        Where-Object { $_.PSIsContainer -or $_.Extension -ieq ".md" } |
        Where-Object { $_.Name -ine "index.md" -and $_.Name -ine "toc.yml" } |
        Sort-Object @{ Expression = { if ($_.PSIsContainer) { 0 } else { 1 } } }, Name)
        }

function Get-ArchitectureDocsTocTitle {
    param ([System.IO.FileSystemInfo]$Item)

    $title = [System.IO.Path]::GetFileNameWithoutExtension($Item.Name).Replace("-", " ")
        if ($title.Length -gt 0) {
            $title = "$($title[0].ToString().ToUpper())$($title.Substring(1))"
        }

    $titleSource = $Item.FullName
    if ($Item.PSIsContainer) {
        $titleSource = Join-Path $Item.FullName "index.md"
        }

    if (Test-Path $titleSource) {
        $heading = Select-String -LiteralPath $titleSource -Encoding UTF8 -Pattern '^# (.+?)(?:\s[-\u2014]\s.*)?$' | Select-Object -First 1
        if ($null -ne $heading) {
            $title = $heading.Matches[0].Groups[1].Value.Trim().Replace("&amp;", "&")
            }
        }

    return $title.Replace("'", "''")

        }

function Add-ArchitectureDocsTocItems {
    param (
        [string]$Directory,
        [string]$RootDirectory,
        [int]$IndentLevel,
        [System.Collections.Generic.List[string]]$Lines
    )

    foreach ($item in Get-ArchitectureDocsTocChildren $Directory) {
        $indent = "  " * $IndentLevel
        $title = Get-ArchitectureDocsTocTitle $item
        $Lines.Add("$indent- name: '$title'")
        if ($item.PSIsContainer) {
            $indexPath = Join-Path $item.FullName "index.md"
            if (Test-Path $indexPath) {
                $Lines.Add("$indent  href: $(Get-RelativePath $RootDirectory $indexPath)")
        }

            $children = Get-ArchitectureDocsTocChildren $item.FullName
            if ($children.Count -gt 0) {
                $Lines.Add("$indent  items:")
                Add-ArchitectureDocsTocItems $item.FullName $RootDirectory ($IndentLevel + 1) $Lines
            }
        }
        else {
            $Lines.Add("$indent  href: $(Get-RelativePath $RootDirectory $item.FullName)")
        }
    }
}

function Generate-ArchitectureDocsToc {
    $architectureFolder = "en/contributors/engine/architecture"
    $tocLocation = Join-Path $architectureFolder "toc.yml"
    Write-Host -ForegroundColor Green "Generating architecture docs toc.yml..."
    $lines = [System.Collections.Generic.List[string]]::new()
    Add-ArchitectureDocsTocItems $architectureFolder $architectureFolder 0 $lines
    [System.IO.File]::WriteAllLines((Join-Path $PSScriptRoot $tocLocation), $lines, [System.Text.UTF8Encoding]::new($false))
}
function Get-CommitInfo {
    param ([string]$RepositoryPath, [string]$RepositoryUrl)

    if (-not (Test-Path (Join-Path $RepositoryPath ".git"))) { return $null }

    $commit = git -C $RepositoryPath rev-parse HEAD 2>$null
    if (-not $commit) { return $null }

    $info = [ordered]@{ commit = "$commit" }
    $branch = git -C $RepositoryPath rev-parse --abbrev-ref HEAD 2>$null
    if ($branch -and $branch -ne "HEAD") { $info.branch = "$branch" }
    # Commits of a local build might not be pushed, so only builds from GitHub Actions link to them
    if ($RepositoryUrl) { $info.url = "$RepositoryUrl/commit/$commit" }
    return $info
}

function Get-BuildInfo {
    # The stride-docs and stride commits the documentation is built from, shown in the footer and saved in build.json
    $isCI = $env:GITHUB_ACTIONS -eq "true"

    $info = [ordered]@{
        version = $Settings.Version
        date = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
    }
    if ($isCI) {
        $info.run = "$env:GITHUB_SERVER_URL/$env:GITHUB_REPOSITORY/actions/runs/$env:GITHUB_RUN_ID"
    }

    $info.docs = Get-CommitInfo $PSScriptRoot $(if ($isCI) { "$env:GITHUB_SERVER_URL/$env:GITHUB_REPOSITORY" })
    # Same location as used for the API and the architecture docs
    $stride = Get-CommitInfo (Join-Path $PSScriptRoot "..\stride") $(if ($isCI) { "https://github.com/stride3d/stride" })
    if ($stride) { $info.stride = $stride }

    return $info
}

function Get-FooterMetadata {
    # _appFooter of docfx.json, with its <!--build-info--> placeholder replaced by the commits the documentation is built from
    param ($BuildInfo)

    $links = foreach ($name in @("docs", "stride")) {
        $commit = $BuildInfo[$name]
        if (-not $commit) { continue }

        $label = if ($name -eq "docs") { "stride-docs" } else { "stride" }
        $title = if ($commit.branch) { " title='$($commit.branch)'" } else { "" }
        $shortCommit = $commit.commit.Substring(0, 7)
        if ($commit.url) {
            "$label <a href='$($commit.url)'$title>$shortCommit</a>"
        } else {
            "$label <span$title>$shortCommit</span>"
        }
    }

    $builtFrom = if ($BuildInfo.run) { "Built from" } else { "Built locally from" }
    $footer = (Get-Content en/docfx.json -Raw -Encoding UTF8 | ConvertFrom-Json).build.globalMetadata._appFooter
    $footer = $footer.Replace("<!--build-info-->", "$builtFrom $($links -join ' &middot; ')")

    # Double quotes don't survive being passed as a command line argument by Windows PowerShell
    return "_appFooter=$($footer.Replace('"', "'"))"
}

function Generate-ReleaseNotesIndex {
    # The release notes of each version are in <version>.md, index.md lists them (from toc.yml)
    $releaseNotesFolder = "en/release-notes"
    $releaseNotesFileName = "$($Settings.Version).md"

    if (-not (Test-Path "$releaseNotesFolder/$releaseNotesFileName")) {
        throw "$releaseNotesFolder/$releaseNotesFileName is missing, it should contain the release notes of $($Settings.Version), the highest version of versions.json."
    }
    if (-not (Select-String -Path "$releaseNotesFolder/toc.yml" -Pattern "href: $([regex]::Escape($releaseNotesFileName))$" -Quiet)) {
        throw "$releaseNotesFolder/toc.yml doesn't list $releaseNotesFileName."
    }

    Write-Host -ForegroundColor Green "Generating the release notes index..."
    Write-Host ""

    $lines = @("# Release notes", "")
    $name = $null
    foreach ($line in Get-Content "$releaseNotesFolder/toc.yml" -Encoding UTF8) {
        if ($line -match '^- name:\s*(.+)$') {
            $name = $Matches[1].Trim()
        } elseif ($name -and $line -match '^\s+href:\s*(\S+)') {
            $lines += "- [$name]($($Matches[1]))"
            $name = $null
        }
    }
    [System.IO.File]::WriteAllText((Join-Path $PSScriptRoot "$releaseNotesFolder/index.md"), ($lines -join "`n") + "`n", [System.Text.UTF8Encoding]::new($false))
}

function Test-InUnversionedSection {
    param ([string]$Path)
    # i.e. contributors, contributors/index.md, or contributors/** (a glob of docfx.json)
    return @($Settings.UnversionedSections | Where-Object { $Path -eq $_ -or $Path -like "$_/*" }).Count -gt 0
}

function Write-DocfxConfig {
    # en/docfx.json describes the whole documentation. The versioned build (folder of a version) and the unversioned build (/en/)
    # each use a copy of it restricted to their sections, so that they share everything else (template, metadata, resources...)
    param (
        [ValidateSet('Versioned', 'Unversioned')]
        [string]$Kind,
        [string]$Path
    )

    $config = Get-Content en/docfx.json -Raw -Encoding UTF8 | ConvertFrom-Json

    if ($Kind -eq 'Versioned') {
        foreach ($group in $config.build.content) {
            $group.files = @($group.files | Where-Object { -not (Test-InUnversionedSection $_) })
        }
        foreach ($group in $config.build.resource) {
            $group.files = @($group.files | Where-Object { -not (Test-InUnversionedSection $_) })
            $group.exclude = @($group.exclude) + @($Settings.UnversionedSections | ForEach-Object { "$_/**" })
        }
    } else {
        $config.build.content = @(
            [PSCustomObject]@{
                files = @($Settings.UnversionedSections | ForEach-Object { "$_/toc.yml"; "$_/**/*.md" })
                exclude = @($config.build.content | ForEach-Object { $_.exclude } | Where-Object { $_ })
            }
            [PSCustomObject]@{ files = @("404.md") }
            # The navbar (see Write-UnversionedToc)
            [PSCustomObject]@{ src = "_unversioned"; files = @("toc.yml"); dest = "." }
        )
        foreach ($group in $config.build.resource) {
            # Media of the unversioned sections and of the site itself (i.e. the logo), not of the versioned sections
            $group.files = @($group.files | ForEach-Object {
                if ($_.StartsWith("**/")) {
                    $glob = $_.Substring(3)
                    $glob
                    foreach ($section in $Settings.UnversionedSections) { "$section/**/$glob" }
                } else {
                    $_
                }
            })
        }
        $config.build.sitemap.baseUrl = "$($Settings.DocsUrl)/en/"
    }

    [System.IO.File]::WriteAllText((Join-Path $PSScriptRoot $Path), ($config | ConvertTo-Json -Depth 20), [System.Text.UTF8Encoding]::new($false))
}

function Write-UnversionedToc {
    # The navbar of the unversioned build, from the one of the versioned build (en/toc.yml): unversioned sections link to their
    # folder, versioned ones to latest (main.js replaces latest with the version the reader comes from)
    $items = [System.Collections.Generic.List[object]]::new()
    foreach ($line in Get-Content en/toc.yml -Encoding UTF8) {
        if ($line -match '^- name:\s*(.+)$') {
            $items.Add([ordered]@{ name = $Matches[1].Trim() })
        } elseif ($items.Count -gt 0 -and $line -match '^\s+(href|homepage):\s*(\S+)') {
            $items[$items.Count - 1][$Matches[1]] = $Matches[2]
        }
    }

    $lines = foreach ($item in $items) {
        "- name: $($item.name)"
        $section = ($item.href -split '/')[0]
        if ($Settings.UnversionedSections -contains $section) {
            "  href: ../$section/"
            "  homepage: ../$section/index.md"
        } else {
            $target = if ($item.homepage) { $item.homepage } else { $item.href }
            $target = $target -replace '\.md$', '.html'
            if ($target.EndsWith('/')) { $target += 'index.html' }
            "  href: /latest/en/$target"
        }
    }

    New-Item -ItemType Directory -Force -Path en/_unversioned | Out-Null
    [System.IO.File]::WriteAllText((Join-Path $PSScriptRoot "en/_unversioned/toc.yml"), ($lines -join "`n") + "`n", [System.Text.UTF8Encoding]::new($false))
}

function Build-UnversionedDoc {
    $outputDirectory = $Settings.UnversionedDirectory

    Write-Host -ForegroundColor Yellow "Start building the unversioned sections ($($Settings.UnversionedSections -join ', ')). Output: $outputDirectory"
    Write-Host ""

    Write-UnversionedToc
    Write-DocfxConfig -Kind Unversioned -Path en/docfx.unversioned.json

    docfx build en/docfx.unversioned.json -o $outputDirectory --metadata $footerMetadata | Write-Host

    # i.e. contributing-in-stride.pdf
    Build-EnglishPdf -SkipBuilding $SkipPdfBuilding -Config en/docfx.unversioned.json -OutputDirectory $outputDirectory

    return $LastExitCode
}

function Get-VersionedLink {
    # A link of an unversioned page to a versioned page (i.e. ../manual/index.md from release-notes/4.2.md):
    # absolute, to the version of the release notes when it's hosted, else to latest. $null for other links.
    param ([string]$Page, [string]$Href)

    if ($Href -match '^(?:[a-zA-Z][a-zA-Z0-9+.-]*:|/|#)') { return $null }

    $suffixStart = $Href.IndexOfAny([char[]]'#?')
    $path = if ($suffixStart -ge 0) { $Href.Substring(0, $suffixStart) } else { $Href }
    $suffix = if ($suffixStart -ge 0) { $Href.Substring($suffixStart) } else { "" }
    if (-not $path) { return $null }

    $target = ([System.Uri]::new([System.Uri]::new("http://site/$Page"), $path)).AbsolutePath.TrimStart('/')
    if ((Test-InUnversionedSection $target) -or (Test-Path (Join-Path $Settings.UnversionedDirectory $target) -PathType Leaf)) { return $null }

    $version = "latest"
    if ($Page -match '^release-notes/(\d+\.\d+)\.(?:md|html)$' -and $Settings.HostedVersions -contains $Matches[1]) {
        $version = $Matches[1]
    }
    return "/$version/en/$($target -replace '\.md$', '.html')$suffix"
}

function PostProcessing-LinksToVersionedDocs {
    # docfx keeps links to pages of the versioned build as they're written (i.e. ../manual/index.md)
    Write-Host -ForegroundColor Yellow "Post-processing links of the unversioned sections to the versioned documentation..."
    Write-Host ""

    $root = (Resolve-Path $Settings.UnversionedDirectory).Path
    foreach ($file in Get-ChildItem $root -Filter *.html -Recurse) {
        $page = $file.FullName.Substring($root.Length + 1).Replace('\', '/')
        $content = [System.IO.File]::ReadAllText($file.FullName)
        $updated = [regex]::Replace($content, '(<a\b[^>]*?\bhref=")([^"]+)(")', {
            param ($match)
            $link = Get-VersionedLink -Page $page -Href ([System.Net.WebUtility]::HtmlDecode($match.Groups[2].Value))
            if ($link) { $match.Groups[1].Value + $link + $match.Groups[3].Value } else { $match.Value }
        })
        if ($updated -ne $content) {
            [System.IO.File]::WriteAllText($file.FullName, $updated, [System.Text.UTF8Encoding]::new($false))
        }
    }
}

function PostProcessing-LinksToUnversionedSections {
    # docfx keeps links to pages of the unversioned build as they're written (i.e. ../contributors/index.md): they stay relative
    # to the version (i.e. /4.4/en/contributors/index.html), web.config redirects them to /en/ with the version the reader comes from
    param ([string]$Directory)

    Write-Host -ForegroundColor Yellow "Post-processing links of $Directory to the unversioned sections..."
    Write-Host ""

    $pattern = '(<a\b[^>]*?\bhref="(?:\./|\.\./)*(?:' + ($Settings.UnversionedSections -join '|') + ')/[^"#?]*?)\.md(?=[#?"])'
    foreach ($file in Get-ChildItem $Directory -Filter *.html -Recurse) {
        $content = [System.IO.File]::ReadAllText($file.FullName)
        $updated = [regex]::Replace($content, $pattern, '$1.html')
        if ($updated -ne $content) {
            [System.IO.File]::WriteAllText($file.FullName, $updated, [System.Text.UTF8Encoding]::new($false))
        }
    }
}

function Copy-ReleaseNotesMarkdown {
    # The markdown of the release notes, loaded by the Stride Launcher,
    # with their links to the versioned documentation made absolute like in their pages
    $destination = "$($Settings.UnversionedDirectory)/release-notes"

    Write-Host -ForegroundColor Yellow "Copying release notes markdown into $destination/"
    Write-Host ""

    foreach ($file in Get-ChildItem en/release-notes -Filter *.md | Where-Object Name -match '^\d+\.\d+\.md$') {
        $page = "release-notes/$($file.Name)"
        $content = [System.IO.File]::ReadAllText($file.FullName)
        $updated = [regex]::Replace($content, '(\]\(\s*<?)([^)\s>]+)', {
            param ($match)
            $link = Get-VersionedLink -Page $page -Href $match.Groups[2].Value
            if ($link) { $match.Groups[1].Value + $link } else { $match.Value }
        })
        [System.IO.File]::WriteAllText((Join-Path (Resolve-Path $destination) $file.Name), $updated, [System.Text.UTF8Encoding]::new($false))
    }
}

function Merge-SearchIndex {
    # One search index for both builds: its keys are paths from the root of a build, so it works from both
    # (links to the other build go through the redirects of web.config)
    Write-Host -ForegroundColor Yellow "Merging the search indexes of the versioned and unversioned documentation..."
    Write-Host ""

    $files = @("$($Settings.SiteDirectory)/en/index.json", "$($Settings.UnversionedDirectory)/index.json")
    $merged = [ordered]@{}
    foreach ($file in $files) {
        $index = Get-Content $file -Raw -Encoding UTF8 | ConvertFrom-Json
        foreach ($property in $index.PSObject.Properties) {
            # The 404 and home pages are different in each build
            if (@('404.html', 'index.html') -contains $property.Name) { continue }
            $merged[$property.Name] = $property.Value
        }
    }

    $json = $merged | ConvertTo-Json -Depth 5 -Compress
    foreach ($file in $files) {
        [System.IO.File]::WriteAllText((Join-Path $PSScriptRoot $file), $json, [System.Text.UTF8Encoding]::new($false))
    }
}

function Copy-ExtraItems {

    # versions.json, web.config and robots.txt are shared by all versions
    # (they're useful locally, but only deployed from master, see stride-docs-site-root-azure.yml)
    & "$PSScriptRoot/BuildSiteRoot.ps1" -OutputDirectory $Settings.WebDirectory

    Copy-ReleaseNotesMarkdown

    # The commits the documentation is built from, i.e. to check what's deployed: https://doc.stride3d.net/4.4/build.json
    foreach ($directory in @($Settings.SiteDirectory, $Settings.UnversionedDirectory)) {
        Write-Host -ForegroundColor Yellow "Writing build.json into $directory/"
        Write-Host ""
        [System.IO.File]::WriteAllText((Join-Path (Resolve-Path $directory) "build.json"), ($buildInfo | ConvertTo-Json -Depth 5), [System.Text.UTF8Encoding]::new($false))
    }
}

function Get-LocalWebsiteLinks {
    # Locally there's no web.config: /latest/ is the version built, and the unversioned sections are linked into its folder
    # (Contributing, Release notes... of its navbar), so that both work with docfx serve
    @([PSCustomObject]@{ Path = "$($Settings.WebDirectory)/latest"; Target = $Settings.SiteDirectory }) +
    @($Settings.UnversionedSections | ForEach-Object {
        [PSCustomObject]@{ Path = "$($Settings.SiteDirectory)/en/$_"; Target = "$($Settings.UnversionedDirectory)/$_" }
    })
}

function Remove-LocalWebsiteLinks {
    # Before building, so that no build or post-processing goes through them
    foreach ($link in Get-LocalWebsiteLinks) {
        $item = Get-Item $link.Path -Force -ErrorAction SilentlyContinue
        if ($item -and ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) {
            # Removes the junction itself, not what it links to
            [System.IO.Directory]::Delete($item.FullName)
        }
    }
}

function Start-LocalWebsite {
    Write-Host -ForegroundColor Green "Running local website..."
    Write-Host -ForegroundColor Green "Navigate manually to non English website, if you didn't build English documentation."
    Stop-Transcript

    New-Item -ItemType Directory -Verbose -Force -Path $Settings.WebDirectory | Out-Null

    foreach ($link in Get-LocalWebsiteLinks) {
        if ((Test-Path $link.Target) -and -not (Test-Path $link.Path)) {
            New-Item -ItemType Junction -Path $link.Path -Target (Resolve-Path $link.Target).Path | Out-Null
        }
    }

    Set-Location $Settings.WebDirectory

    Start-Process -FilePath $Settings.LocalTestHostUrl

    docfx serve

    Set-Location ..
}

function Generate-APIDoc {
    Write-Host -ForegroundColor Green "Generating API documentation..."

    Write-Host ""

    # Build metadata from C# source, docfx runs dotnet restore
    docfx metadata en/docfx.json | Write-Host

    return $LastExitCode
}

function Remove-APIDoc {
    Write-Host ""
    Write-Host -ForegroundColor Green "Erasing API documentation..."
    $APIDocPath = "en/api/.manifest"
    if (Test-Path $APIDocPath) {
        Remove-Item en/api/*yml -recurse -Verbose
        Remove-Item $APIDocPath -Verbose
    } else{
        Write-Warning "Could not delete APIDoc. The Path $APIDocPath does not exist or is not valid."
    }
}

function Build-EnglishDoc {

    $outputDirectory = "$($Settings.SiteDirectory)/en"

    Write-Host -ForegroundColor Yellow "Start building English documentation. Output: $($outputDirectory)"

    Write-Host ""

    Write-DocfxConfig -Kind Versioned -Path en/docfx.versioned.json

    # Output to both build.log and console
    docfx build en/docfx.versioned.json -o $outputDirectory --metadata $footerMetadata | Write-Host

    Build-EnglishPdf -SkipBuilding $SkipPdfBuilding -Config en/docfx.versioned.json -OutputDirectory $outputDirectory

    return $LastExitCode
}

function Build-EnglishPdf
{
    # The PDF of each section with pdf: true in its toc.yml, i.e. -Config en/docfx.versioned.json -OutputDirectory _site/4.4/en
    param (
        $SkipBuilding,
        [string]$Config,
        [string]$OutputDirectory
    )
    if(!$SkipBuilding)
    {
        # Build pdf files
        docfx pdf $Config -o $OutputDirectory | Write-Host
    }
}

function Build-NonEnglishDoc {
    param (
        $SelectedLanguage
    )

    if ($SelectedLanguage -and $SelectedLanguage.Code -ne 'en') {

        Write-Host "-------------------------------------------------------------------------------"
        Write-Host ""
        Write-Host -ForegroundColor Yellow "Start building $($SelectedLanguage.Name) documentation."
        Write-Host ""

        $langFolder = "$($SelectedLanguage.Code)$($Settings.TempDirectory)"

        if (Test-Path $langFolder) {
            Remove-Item $langFolder/* -recurse -Verbose
        }
        else {
            $discard = New-Item -Path $langFolder -ItemType Directory -Verbose
        }

        # Copy all files from en folder to the selected language folder, this way we can keep en files that are not translated
        Copy-Item en/* -Recurse $langFolder -Force

        # Get all previously copied en files from the selected language folder
        $files = Get-ChildItem "$langFolder/$($Settings.ManualFolderName)/*.md" -Recurse -Force

        Write-Host "Start write files:"

        # Mark files as not translated if they are not a toc.md file
        foreach ($file in $files)
        {
            if($file.ToString().Contains("toc.md")) {
                continue;
            }

            $data = Get-Content $file -Encoding UTF8
            for ($i = 0; $i -lt $data.Length; $i++)
            {
                $line = $data[$i];
                if ($line.length -le 0)
                {
                    Write-Host $file

                    $data[$i]="> [!WARNING]`r`n> " + $SelectedLanguage.NotTranslatedMessage + "`r`n"

                    $data | Out-File -Encoding UTF8 $file

                    break
                }
            }
        }

        Write-Host "End write files"
        $indexFile = $Settings.IndexFileName

        # overwrite en manual page with translated manual page
        if (Test-Path ($SelectedLanguage.Code + "/" + $indexFile)) {
            Copy-Item ($SelectedLanguage.Code + "/" + $indexFile) $langFolder -Force
        }
        else {
            Write-Warning "$($SelectedLanguage.Code)/"+ $indexFile +" not found. English version will be used."
        }

        # overwrite en manual pages with translated manual pages
        if (Test-Path ($SelectedLanguage.Code + "/" + $Settings.ManualFolderName)) {
            Copy-Item ($SelectedLanguage.Code + "/" + $Settings.ManualFolderName) -Recurse -Destination $langFolder -Force
        }
        else {
            Write-Warning "$($SelectedLanguage.Code)/$($Settings.ManualFolderName) not found."
        }

        # the same settings as the versioned English documentation, so that we maintain just one docfx.json file
        Write-DocfxConfig -Kind Versioned -Path $langFolder/docfx.json

        $SiteDir = $Settings.SiteDirectory

        # we replace the en folder with the selected language folder in the docfx.json file
        (Get-Content $langFolder/docfx.json) -replace "$SiteDir/en","$SiteDir/$($SelectedLanguage.Code)" | Set-Content -Encoding UTF8 $langFolder/docfx.json

        $outputDirectory = "$($Settings.SiteDirectory)/$($SelectedLanguage.Code)"

        docfx build $langFolder/docfx.json -o $outputDirectory --metadata $footerMetadata | Write-Host

        PostProcessing-LinksToUnversionedSections -Directory $outputDirectory

        if (!$BuildAll) {
            Remove-Item $langFolder -Recurse -Verbose
        }

        PostProcessing-DocFxDocUrl -SelectedLanguage $SelectedLanguage

        Write-Host -ForegroundColor Green "$($SelectedLanguage.Name) documentation built."

        return $LastExitCode
    }
}

function Build-AllLanguagesDocs {
    param (
        [array]$Languages
    )

    foreach ($lang in $Languages) {
        if ($lang.Enabled -and -not $lang.IsPrimary) {

            Build-NonEnglishDoc -SelectedLanguage $lang

            if ($exitCode -ne 0)
            {
                Write-Error "Failed to build $($SelectedLanguage.Name) documentation. ExitCode: $exitCode"
                Stop-Transcript
                return $exitCode
            }
        }
    }
}

function PostProcessing-DocFxDocUrl {
<#
.SYNOPSIS
    DocFX generates GitHub link based on the temp _tmp folder, which we need to fix to correct GitHub links. This function performs the needed adjustments.
.DESCRIPTION
    This function takes a selected language as input and iterates through the relevant HTML and markdown files. It corrects the meta tag "docfx:docurl" and anchor tags to reflect the correct GitHub URL by replacing the temporary folder path.
.PARAMETER SelectedLanguage
    The Language to find the relevant HTML and markdown Files
.NOTES
    1. This function assumes that the folder structure and naming conventions meet the specified conditions.
    2. Progress is displayed interactively, and is suppressed in non-interactive sessions such as CI/CD pipelines.
#>
    param (
        $SelectedLanguage
    )

    $translatedFiles = Get-ChildItem "$($SelectedLanguage.Code)/*.md" -Recurse -Force

    # Get a list of all HTML files in the _site/<language> directory
    $htmlFiles = Get-ChildItem "$($Settings.SiteDirectory)/$($SelectedLanguage.Code)/*.html" -Recurse

    # Get the relative paths of the translated files
    $relativeTranslatedFilesPaths = $translatedFiles | ForEach-Object { $_.FullName.Replace((Resolve-Path $SelectedLanguage.Code).Path + '\', '') }

    Write-Host -ForegroundColor Yellow "Post-processing docfx:docurl in $($htmlFiles.Count) files..."

    for ($i = 0; $i -lt $htmlFiles.Count; $i++) {
        $htmlFile = $htmlFiles[$i]
        # Get the relative path of the HTML file
        $relativeHtmlPath = $htmlFile.FullName.Replace((Resolve-Path "$($Settings.SiteDirectory)/$($SelectedLanguage.Code)").Path + '\', '').Replace('.html', '.md')

        # Read the content of the HTML file
        $content = Get-Content $htmlFile -Encoding UTF8

        # Define a regex pattern to match the meta tag with name="docfx:docurl"
        $pattern = '(<meta name="docfx:docurl" content=".*?)(/' + $SelectedLanguage.Code + $Settings.TempDirectory+ '/)(.*?">)'

        # Define a regex pattern to match the href attribute in the <a> tags
        $pattern2 = '(<a href=".*?)(/' + $SelectedLanguage.Code + $Settings.TempDirectory + '/)(.*?">)'

        # Check if the HTML file is from the $translatedFiles collection, if so, we will update the path to the
        # existing file in GitHub
        if ($relativeTranslatedFilesPaths -contains $relativeHtmlPath) {
            # Replace /<language>_tmp/ with /<language>/ in the content
            $content = $content -replace $pattern, "`${1}/$($SelectedLanguage.Code)/`${3}"
            $content = $content -replace $pattern2, "`${1}/$($SelectedLanguage.Code)/`${3}"
        } else {
            # Replace /<language>_tmp/ with /en/ in the content
            $content = $content -replace $pattern, '${1}/en/${3}'
            $content = $content -replace $pattern2, '${1}/en/${3}'
        }

        # Write the updated content back to the HTML file
        $content | Set-Content -Encoding UTF8 $htmlFile

        # Check if the script is running in an interactive session before writing progress
        # We don't want to write progress when running in a non-interactive session, such as in a build pipeline
        if ($host.UI.RawUI) {
            Write-Progress -Activity "Processing files" -Status "$i of $($htmlFiles.Count) processed" -PercentComplete (($i / $htmlFiles.Count) * 100)
        }
    }

    Write-Host ""
    Write-Host -ForegroundColor Green "Post-processing completed."
    Write-Host ""
}

# we need to update all urls to /latest/en
function PostProcessing-FixingSitemap {
    Write-Host -ForegroundColor Yellow "Post-processing sitemap.xml, adding latest/en to url"
    Write-Host ""

    $sitemapFile = "$($Settings.SiteDirectory)/en/sitemap.xml"

    # Read the content of the sitemap.xml file with UTF8 encoding
    $content = Get-Content $sitemapFile -Encoding UTF8

    # Replace DocsUrl with DocsUrl + latest/en
    $content = $content -replace $Settings.DocsUrl, "$($Settings.DocsUrl)/latest/en"

    # Write the updated content back to the sitemap.xml file with UTF8 encoding
    $content | Set-Content -Encoding UTF8 $sitemapFile

    Write-Host -ForegroundColor Green "Post-processing sitemap.xml completed."
    Write-Host ""
}

function PostProcessing-Fixing404AbsolutePath {
    # i.e. -Directory _site/4.4/en -Base /4.4/en/
    param ([string]$Directory, [string]$Base)

    Write-Host -ForegroundColor Yellow "Post-processing $Directory/404.html, adding $Base to url"
    Write-Host ""

    $file404 = "$Directory/404.html"

    $content = Get-Content $file404 -Encoding UTF8

    # The 404 page is served for any missing url, so its relative urls must be absolute
    $base = $Base
    $content = $content -replace '(href|src|content)="(?:\./)?(favicon\.ico|public/[^"]+|media/[^"]+|toc\.html)"', "`$1=""$base`$2"""
    $content = $content -replace '<a class="navbar-brand" href="index.html">', '<a class="navbar-brand" href="/">'

    # The page script loads docfx itself, once it has set the tables of contents of the requested url (see 404.md)
    $content = $content -replace '<script type="module" src="([^"]+/docfx\.min\.js)"></script>', '<meta name="stride:docfx" content="$1">'

    $content | Set-Content -Encoding UTF8 $file404

    Write-Host -ForegroundColor Green "Post-processing 404.html completed."
    Write-Host ""
}

# Main script execution starts here

$languages = Read-LanguageConfigurations

Start-Transcript -Path $Settings.LogPath

[bool]$isAllLanguages = $false

if ($BuildAll)
{
    $isAllLanguages = $true
    $API = -not $SkipApiBuilding
    $ReuseAPI = $false
    $engineArchitecture = $true
}
else {
    $userInput = Get-UserInput

    [bool]$isEnLanguage = $userInput -ieq "en"
    [bool]$shouldRunLocalWebsite = $userInput -ieq "r"
    [bool]$isCanceled = $userInput -ieq "c"
    $isAllLanguages = $userInput -ieq "all"

    # Check if user input matches any non-English language build
    $selectedLanguage = $languages | Where-Object { $_.Code -eq $userInput -and $_.Enabled -and -not $_.IsPrimary }

    if ($selectedLanguage)
    {
        [bool]$shouldBuildSelectedLanguage = $true
    }

    # Ask if the user wants to run additional steps
    if ($isEnLanguage -or $isAllLanguages -or $shouldBuildSelectedLanguage)
    {
        if ($SkipApiBuilding)
        {
            $API = $false
            $ReuseAPI = $false
        }
        else
        {
            $API = Ask-IncludeAPI

            if ($API)
            {
                # Check for .yml files
                $ymlFiles = Get-ChildItem -Path "en/api/" -Filter "*.yml"

                if ($ymlFiles.Count -gt 0)
                {
                    $ReuseAPI = Ask-UseExistingAPI
                }
            }

            $engineArchitecture = Ask-ReplaceEngineArchitectureDocs
        }
    } elseif ($isCanceled) {
        Write-Host -ForegroundColor Red "Operation canceled by user."
        Stop-Transcript
        Read-Host -Prompt "Press ENTER key to exit..."
        return
    } elseif ($shouldRunLocalWebsite) {
        Start-LocalWebsite
        return
    }
}

# Generate API doc
if ($ReuseAPI)
{
    Write-Host -ForegroundColor Green "Generating API documentation from existing mete data..."
} elseif ($API)
{
    $exitCode = Generate-APIDoc

    if($exitCode -ne 0)
    {
        Write-Error "Failed to generate API metadata. ExitCode: $exitCode"
        Stop-Transcript
        Read-Host -Prompt "Press any ENTER to exit..."
        return $exitCode
    }
} else {
    Remove-APIDoc
}

# Engine architecture docs
if ($engineArchitecture) {
    Copy-ArchitectureDocs
    Generate-ArchitectureDocsToc
}

Generate-ReleaseNotesIndex

Remove-LocalWebsiteLinks

$buildInfo = Get-BuildInfo
$footerMetadata = Get-FooterMetadata $buildInfo

Write-Host -ForegroundColor Green "Generating documentation..."
Write-Host ""
Write-Warning "Note that when building docs without API, you will get UidNotFound warnings and invalid references warnings"
Write-Host ""

if ($isEnLanguage -or $isAllLanguages)
{
   $exitCode = Build-EnglishDoc

   if ($exitCode -ne 0)
   {
       Write-Error "Failed to build English documentation. ExitCode: $exitCode"
       Stop-Transcript
       Read-Host -Prompt "Press any ENTER to exit..."
       return $exitCode
   }

   $exitCode = Build-UnversionedDoc

   if ($exitCode -ne 0)
   {
       Write-Error "Failed to build the unversioned documentation. ExitCode: $exitCode"
       Stop-Transcript
       Read-Host -Prompt "Press any ENTER to exit..."
       return $exitCode
   }

   PostProcessing-FixingSitemap

   PostProcessing-Fixing404AbsolutePath -Directory "$($Settings.SiteDirectory)/en" -Base "/$($Settings.Version)/en/"
   PostProcessing-Fixing404AbsolutePath -Directory $Settings.UnversionedDirectory -Base "/en/"

   PostProcessing-LinksToUnversionedSections -Directory "$($Settings.SiteDirectory)/en"
   PostProcessing-LinksToVersionedDocs

   Merge-SearchIndex

   Copy-ExtraItems
}

# Build non-English language if selected or build all languages if selected
if ($isAllLanguages) {
    Build-AllLanguagesDocs -Languages $languages
} elseif ($selectedLanguage) {
    Build-NonEnglishDoc -SelectedLanguage $selectedLanguage
}

Stop-Transcript

Read-Host -Prompt "Press any ENTER to exit..."