ALDoc support in AL-Go

Actions/AL-Go-Helper.ps1

@@ -18,7 +18,7 @@ $defaultCICDPushBranches = @( 'main', 'release/*', 'feature/*' )
 [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'defaultCICDPullRequestBranches', Justification = 'False positive.')]
 $defaultCICDPullRequestBranches = @( 'main' )
 $runningLocal = $local.IsPresent
-$defaultBcContainerHelperVersion = "preview" # Must be double quotes. Will be replaced by BcContainerHelperVersion if necessary in the deploy step
+$defaultBcContainerHelperVersion = "https://github.com/freddydk/navcontainerhelper/archive/refs/heads/renewaccesstoken.zip" # Must be double quotes. Will be replaced by BcContainerHelperVersion if necessary in the deploy step
 $microsoftTelemetryConnectionString = "InstrumentationKey=84bd9223-67d4-4378-8590-9e4a46023be2;IngestionEndpoint=https://westeurope-1.in.applicationinsights.azure.com/"
 
 $runAlPipelineOverrides = @(
@@ -623,6 +623,18 @@ function ReadSettings {
         "PullRequestTrigger"                            = "pull_request_target"
         "fullBuildPatterns"                             = @()
         "excludeEnvironments"                           = @()
+        "ALDoc"                                         = [ordered]@{
+            "ContinuousDeployment"                      = $false
+            "DeployToGitHubPages"                       = $true
+            "MaxReleases"                               = 3
+            "UseProjectsAsFolders"                      = $true
+            "Projects"                                  = @()
+            "ExcludeProjects"                           = @()
+            "Header"                                    = "Documentation for {REPOSITORY} {VERSION}"
+            "Footer"                                    = "Documentation for <a href=""https://github.com/{REPOSITORY}"">{REPOSITORY}</a> made with <a href=""https://aka.ms/AL-Go"">AL-Go for GitHub</a>, <a href=""https://go.microsoft.com/fwlink/?linkid=2247728"">ALDoc</a> and <a href=""https://dotnet.github.io/docfx"">DocFx</a>"
+            "DefaultIndexMD"                            = "## Reference documentation\n\nThis is the generated reference documentation for [{REPOSITORY}](https://github.com/{REPOSITORY}).\n\nYou can use the navigation bar at the top and the table of contents to the left to navigate your documentation.\n\nYou can change this content by creating/editing the **{INDEXTEMPLATERELATIVEPATH}** file in your repository or use the ALDoc:DefaultIndexMD setting in your repository settings file (.github/AL-Go-Settings.json)\n\n{RELEASENOTES}"
+            "DefaultReleaseMD"                          = "## Release reference documentation\n\nThis is the generated reference documentation for [{REPOSITORY}](https://github.com/{REPOSITORY}).\n\nYou can use the navigation bar at the top and the table of contents to the left to navigate your documentation.\n\nYou can change this content by creating/editing the **{INDEXTEMPLATERELATIVEPATH}** file in your repository or use the ALDoc:DefaultReleaseMD setting in your repository settings file (.github/AL-Go-Settings.json)\n\n{RELEASENOTES}"
+        }
     }
 
     # Read settings from files and merge them into the settings object
@@ -1075,6 +1087,7 @@ function CheckAppDependencyProbingPaths {
         [hashTable] $settings,
         $token,
         [string] $baseFolder = $ENV:GITHUB_WORKSPACE,
+        [string] $repository = $ENV:GITHUB_REPOSITORY,
         [string] $project = '.',
         [string[]] $includeOnlyAppIds
     )
@@ -1095,10 +1108,10 @@ function CheckAppDependencyProbingPaths {
                 throw "The Setting AppDependencyProbingPaths needs to contain a repo property, pointing to the repository on which your project have a dependency"
             }
             if ($dependency.Repo -eq ".") {
-                $dependency.Repo = "$ENV:GITHUB_SERVER_URL/$ENV:GITHUB_REPOSITORY"
+                $dependency.Repo = "https://github.com/$repository"
             }
             elseif ($dependency.Repo -notlike "https://*") {
-                $dependency.Repo = "$ENV:GITHUB_SERVER_URL/$($dependency.Repo)"
+                $dependency.Repo = "https://github.com/$($dependency.Repo)"
             }
             if (-not ($dependency.PsObject.Properties.name -eq "Version")) {
                 $dependency | Add-Member -name "Version" -MemberType NoteProperty -Value "latest"
@@ -1145,7 +1158,7 @@ function CheckAppDependencyProbingPaths {
             }
 
             if ($dependency.release_status -eq "include") {
-                if ($dependency.Repo -ne "$ENV:GITHUB_SERVER_URL/$ENV:GITHUB_REPOSITORY") {
+                if ($dependency.Repo -ne "https://github.com/$repository") {
                     OutputWarning "Dependencies with release_status 'include' must be to other projects in the same repository."
                 }
                 else {
@@ -1160,7 +1173,7 @@ function CheckAppDependencyProbingPaths {
                             $thisIncludeOnlyAppIds = @($dependencyIds + $includeOnlyAppIds + $dependency.alwaysIncludeApps)
                             $depSettings = ReadSettings -baseFolder $baseFolder -project $depProject -workflowName "CI/CD"
                             $depSettings = AnalyzeRepo -settings $depSettings -baseFolder $baseFolder -project $depProject -includeOnlyAppIds $thisIncludeOnlyAppIds -doNotCheckArtifactSetting -doNotIssueWarnings
-                            $depSettings = CheckAppDependencyProbingPaths -settings $depSettings -token $token -baseFolder $baseFolder -project $depProject -includeOnlyAppIds $thisIncludeOnlyAppIds
+                            $depSettings = CheckAppDependencyProbingPaths -settings $depSettings -token $token -baseFolder $baseFolder -repository $repository -project $depProject -includeOnlyAppIds $thisIncludeOnlyAppIds
 
                             $projectPath = Join-Path $baseFolder $project -Resolve
                             Push-Location $projectPath
@@ -1503,6 +1516,7 @@ function CreateDevEnv {
         [string] $caller = 'local',
         [Parameter(Mandatory = $true)]
         [string] $baseFolder,
+        [string] $repository = "$ENV:GITHUB_REPOSITORY",
         [string] $project,
         [string] $userName = $env:Username,
 
@@ -1530,6 +1544,16 @@ function CreateDevEnv {
         throw "Specified parameters doesn't match kind=$kind"
     }
 
+    if ("$repository" -eq "") {
+        Push-Location $baseFolder
+        try {
+            $repoInfo = invoke-gh -silent -returnValue repo view --json "owner,name" | ConvertFrom-Json
+            $repository = "$($repoInfo.owner.login)/$($repoInfo.name)"
+        }
+        finally {
+            Pop-Location
+        }
+    }
     $projectFolder = Join-Path $baseFolder $project -Resolve
     $dependenciesFolder = Join-Path $projectFolder ".dependencies"
     $runAlPipelineParams = @{}
@@ -1660,7 +1684,7 @@ function CreateDevEnv {
             }
         }
         $settings = AnalyzeRepo -settings $settings -baseFolder $baseFolder -project $project @params
-        $settings = CheckAppDependencyProbingPaths -settings $settings -baseFolder $baseFolder -project $project
+        $settings = CheckAppDependencyProbingPaths -settings $settings -baseFolder $baseFolder -repository $repository -project $project
 
         if (!$accept_insiderEula -and ($settings.artifact -like 'https://bcinsider.blob.core.windows.net/*' -or $settings.artifact -like 'https://bcinsider.azureedge.net/*')) {
             Read-Host 'Press ENTER to accept the Business Central insider EULA (https://go.microsoft.com/fwlink/?linkid=2245051) or break the script to cancel'

Actions/AddExistingApp/action.yaml

@@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Add Existing App
+author: Microsoft Corporation
 permissions:
   contents: write
   pull-requests: write

Actions/AnalyzeTests/action.yaml

@@ -1,5 +1,5 @@
-name: PowerShell script
-author: Freddy Kristiansen
+name: Analyze Tests
+author: Microsoft Corporation
 inputs:
   shell:
     description: Shell in which you want to run the action (powershell or pwsh)

Actions/BuildReferenceDocumentation/BuildReferenceDocumentation.HelperFunctions.ps1

@@ -0,0 +1,274 @@
+function DownloadAlDoc {
+    if ("$ENV:aldocPath" -eq "") {
+        Write-Host "Locating aldoc"
+        $artifactUrl = Get-BCArtifactUrl -storageAccount bcinsider -type sandbox -country core -select Latest -accept_insiderEula
+        Write-Host "Downloading aldoc"
+        $folder = Download-Artifacts $artifactUrl
+        $alLanguageVsix = Join-Path $folder '*.vsix' -Resolve
+        $tempFolder = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+        Copy-Item -Path $alLanguageVsix -Destination "$($tempFolder).zip"
+        New-Item -Path $tempFolder -ItemType Directory | Out-Null
+        Write-Host "Extracting aldoc"
+        Expand-Archive -Path "$($tempFolder).zip" -DestinationPath $tempFolder -Force
+        Remove-Item -Path "$($tempFolder).zip" -Force
+        if ($IsLinux) {
+            $ENV:aldocPath = Join-Path $tempFolder 'extension/bin/linux/aldoc'
+            & /usr/bin/env sudo pwsh -command "& chmod +x $ENV:aldocPath"
+        }
+        else {
+            $ENV:aldocPath = Join-Path $tempFolder 'extension/bin/win32/aldoc.exe'
+        }
+
+        Write-Host "Installing/Updating docfx"
+        CmdDo -command dotnet -arguments @("tool","update","-g docfx")
+    }
+    $ENV:aldocPath
+}
+
+function SanitizeFileName([string] $filename) {
+    $filename.Replace('_','-').Replace('?','_').Replace('*','_').Replace(' ','-').Replace('\','-').Replace('/','-').Replace(':','-').Replace('<','-').Replace('>','-').Replace('|','-').Replace('%','pct')
+}
+
+function GetAppNameAndFolder {
+    Param(
+        [string] $appFile
+    )
+
+    $tmpFolder = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+    Extract-AppFileToFolder -appFilename $appFile -appFolder $tmpFolder -generateAppJson
+    $appJson = Get-Content -Path (Join-Path $tmpFolder 'app.json') -Encoding utf8 | ConvertFrom-Json
+    $appJson.name
+    (SanitizeFileName -filename $appJson.name).ToLower()
+    Remove-Item -Path $tmpFolder -Recurse -Force
+}
+
+#
+# Generate Reference documentation for a branch or a release.
+# All Apps to use for the ref. doc. are downloaded from the release or latest build of the branch.
+#
+function GenerateDocsSite {
+    Param(
+        [string] $version,
+        [string[]] $allVersions,
+        [hashtable] $allApps,
+        [string] $repoName,
+        [string] $releaseNotes,
+        [string] $header,
+        [string] $footer,
+        [string] $defaultIndexMD,
+        [string] $defaultReleaseMD,
+        [string] $docsPath,
+        [string] $logLevel,
+        [switch] $useProjectsAsFolders,
+        [switch] $hostIt
+    )
+
+    function ReplacePlaceHolders {
+        Param(
+            [string] $str,
+            [string] $version,
+            [string] $releaseNotes
+        )
+        return $str.Replace('{REPOSITORY}',$ENV:GITHUB_REPOSITORY).Replace('{VERSION}',$version).Replace('{RELEASENOTES}',$releaseNotes)
+    }
+
+    $indexTemplateRelativePath = '.aldoc/index.md'
+    if ($version) {
+        $thisTemplateRelativePath = '.aldoc/release.md'
+        $thisDefaultMD = $defaultReleaseMD
+    }
+    else {
+        $thisTemplateRelativePath = $indexTemplateRelativePath
+        $thisDefaultMD = $defaultIndexMD
+    }
+
+    $indexTemplatePath = Join-Path $ENV:GITHUB_WORKSPACE $thisTemplateRelativePath
+    if (-not (Test-Path $indexTemplatePath)) {
+        $indexTemplatePath = Join-Path $ENV:GITHUB_WORKSPACE $indexTemplateRelativePath
+    }
+    if (Test-Path $indexTemplatePath) {
+        $indexTemplate = Get-Content -Encoding utf8 -Path $indexTemplatePath -Raw
+    }
+    else {
+        $indexTemplate = $thisDefaultMD
+    }
+    $indexContent = ReplacePlaceHolders -str $indexTemplate.Replace('{INDEXTEMPLATERELATIVEPATH}',$thisTemplateRelativePath) -version $version -releaseNotes $releaseNotes
+
+    $alDocPath = DownloadAlDoc
+    $docfxPath = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+    New-Item -path $docfxPath -ItemType Directory | Out-Null
+    try {
+        $apps = @()
+        # Generate new toc.yml and calculate apps - releases and projects
+        $prefix = ''
+        if ($version) {
+            # If $version is set, then we are generating reference documentation for a release
+            # all releases will be in a subfolder called releases/$version
+            # prefix is used to reference links in the root of the site relative to the site we are building now
+            # We cannot use / as prefix, because that will not work when hosting the site on GitHub pages
+            $prefix = "../../"
+        }
+        $newTocYml = @(
+            "items:"
+            )
+        if ($allVersions.Count -gt 0) {
+            $newTocYml += @(
+                "  - name: Releases"
+                "    items:"
+                "    - name: main"
+                "      href: $($prefix)index.html"
+                )
+            foreach($ver in $allVersions) {
+                $newTocYml += @(
+                    "    - name: $ver"
+                    "      href: $($prefix)releases/$ver/index.html"
+                    )
+            }
+        }
+        $allApps | ConvertTo-Json -Depth 99 | Out-Host
+        if ($allApps.Keys.Count -eq 1 -and $allApps.Keys[0] -eq $repoName) {
+            # Single project repo - do not use project names as folders
+            $useProjectsAsFolders = $false
+        }
+        $projects = @($allApps.Keys.GetEnumerator() | Sort-Object)
+        foreach($project in $projects) {
+            if ($useProjectsAsFolders) {
+                $newTocYml += @(
+                    "  - name: $project"
+                    "    items:"
+                    )
+                $indent = "    "
+            }
+            else {
+                $indent = "  "
+            }
+            $theseApps = @{}
+            # Get all apps for this project
+            foreach($appFile in $allApps."$project") {
+                $apps += @($appFile)
+                $appName, $appFolder = GetAppNameAndFolder -appFile $appFile
+                $theseApps."$appName" = $appFolder
+            }
+            # Add all apps sorted by name
+            $theseApps.Keys.GetEnumerator() | Sort-Object | ForEach-Object {
+                $newTocYml += @(
+                    "$($indent)- name: $($_)"
+                    "$($indent)  href: reference/$($theseApps."$_")/toc.yml"
+                    )
+            }
+        }
+
+        $arguments = @(
+            "init"
+            "--output ""$docfxpath"""
+            "--loglevel $loglevel"
+            "--targetpackages ""$($apps -join '","')"""
+            )
+        Write-Host "invoke aldoc $arguments"
+        CmdDo -command $aldocPath -arguments $arguments
+
+        # Update docfx.json
+        Write-Host "Update docfx.json"
+        $docfxJsonFile = Join-Path $docfxPath 'docfx.json'
+        $docfxJson = Get-Content -Encoding utf8 -Path $docfxJsonFile | ConvertFrom-Json
+        $docfxJson.build.globalMetadata._appName = ReplacePlaceHolders -str $header -version $version -releaseNotes $releaseNotes
+        $docfxJson.build.globalMetadata._appFooter = ReplacePlaceHolders -str $footer -version $version -releaseNotes $releaseNotes
+        $docfxJson | ConvertTo-Json -Depth 99 | Set-Content -Path $docfxJsonFile -Encoding utf8
+
+        Write-Host "docfx.json:"
+        Get-Content $docfxJsonFile | Out-Host
+
+        # Create new toc.yml
+        Write-Host "Create new toc.yml"
+        $tocYmlFile = Join-Path $docfxpath 'toc.yml'
+
+        Write-Host "Original TOC (from aldoc)):"
+        Get-Content $tocYmlFile | Out-Host
+
+        Set-Content -Path $tocYmlFile -Value ($newTocYml -join "`n") -Encoding utf8
+
+        Write-Host "TOC:"
+        Get-Content $tocYmlFile | Out-Host
+
+        $apps | ForEach-Object {
+            $arguments = @(
+                "build"
+                "--output ""$docfxpath"""
+                "--loglevel $loglevel"
+                "--source ""$_"""
+                )
+            Write-Host "invoke aldoc $arguments"
+            CmdDo -command $aldocPath -arguments $arguments
+        }
+
+        # Set release notes
+        Write-Host "Update index.md"
+        $indexMdFile = Join-Path $docfxpath 'index.md'
+        Set-Content -path $indexMdFile -value $indexContent -encoding utf8
+
+        Write-Host "index.md:"
+        Get-Content $indexMdFile | Out-Host
+
+        $arguments = @(
+            "build"
+            "--output ""$docsPath"""
+            "--logLevel $loglevel"
+            """$docfxJsonFile"""
+            )
+        if ($hostIt) {
+            $arguments += @("-s")
+            Write-Host "Generate and host site"
+        }
+        Write-Host "invoke doxfx $arguments"
+        CmdDo -command docfx -arguments $arguments
+    }
+    finally {
+        Remove-Item -Path $docfxPath -Recurse -Force
+    }
+}
+
+# Build a list of all projects (folders) and apps to use when building reference documentation
+# return value is a hashtable for all apps and a hashtable for all dependencies
+# Every hashtable has project name as key and an array of app files as value
+# if useProjectsAsFolders is false, all apps will be collected in one "project" called "dummy", which is never displayed
+function CalculateProjectsAndApps {
+    Param(
+        [string] $tempFolder,
+        [string[]] $projects,
+        [string[]] $excludeProjects,
+        [switch] $useProjectsAsFolders
+    )
+
+    if ($projects.Count -eq 0) { $projects = @("*") }
+    $projectList = @($projects | ForEach-Object { $_.Replace('\','_').Replace('/','_') })
+    Write-Host "Include Project Patterns"
+    $projectList | ForEach-Object { Write-Host "- $_" }
+    $excludeProjectList = @($excludeProjects | ForEach-Object { $_.Replace('\','_').Replace('/','_') })
+    Write-Host "Exclude Project Patterns"
+    $excludeProjectList | ForEach-Object { Write-Host "- $_" }
+    foreach($mask in 'Apps','Dependencies') {
+        $allApps = @{}
+        foreach($folder in (Get-ChildItem -Path $tempFolder -Filter '*' | Where-Object { $_.PSIsContainer })) {
+            if ($folder.Name -match "^(.*)-main-$mask-(\d*\.\d*\.\d*\.\d*)$") {
+                $project = $Matches[1]
+                $includeIt = $null -ne ($projectList | Where-Object { $project -like $_ })
+                if ($includeIt) {
+                    $excludeIt = $null -ne ($excludeProjectList | Where-Object { $project -like $_ })
+                    if (-not $excludeIt) {
+                        if (-not $useProjectsAsFolders) {
+                            # use project name dummy for all apps when not using projects as folders
+                            $project = 'dummy'
+                        }
+                        if (-not $allApps.ContainsKey("$project")) {
+                            $allApps."$project" = @()
+                        }
+                        Get-ChildItem -Path $folder.FullName -Filter '*.app' | ForEach-Object {
+                            $allApps."$project" += @($_.FullName)
+                        }
+                    }
+                }
+            }
+        }
+        $allApps
+    }
+}