ALDoc support in AL-Go (#760)

# TO:DO ```[tasklist] # Tasks - [x] Create new Action: BuildALDoc to build reference documentation - [x] Create new job in CI/CD to build and publish reference documentation - [x] Create reference documentation for x versions of the apps. - [x] Create new workflow for publishing ALDoc reference documentation - [x] Only allow publishing reference documentation if GitHub Pages is set to GitHub Actions - [x] Add release notes - [x] Add documentation - [x] Add end 2 end test ``` # Implementation ## New Settings: ALDoc structure The following settings structure will be added to repository settings (with default values): ``` "ALDoc" = [ordered]@{ "ContinuousDeployment" = $false "DeployToGitHubPages" = $true "MaxReleases" = 3 "Projects" = @() "ExcludeProjects" = @() "Header" = "Documentation for {REPOSITORY} {VERSION}" "Footer" = "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}" } ``` Where: - ALDoc.ContinuousDeployment controls whether or not to run continuous deployment of reference documentation - ALDoc.DeployToGitHubPages determines whether or not the generated reference documentation is deployed to the repo's GitHub pages site. - ALDoc.MaxReleases is the number of releases to include in the reference documentation - ALDoc.Projects is an array of projects to include in the reference documentation - ALDoc.ExcludeProjects is an array of projects to exclude in the reference documentation - ALDoc.Header and ALDoc.Footer are the header and footer markdown of the reference documentation - ALDOc.DefaultIndexMD is the default markdown to use for the landing page of the reference documentation - ALDoc.DefaultReleaseMD is the default markdown to use for the landing page of a release in the reference documentation ALDoc.Header, ALDoc.Footer, ALDoc.DefaultIndexMD and ALDoc.DefaultReleaseMD can have the following placeholders, which will be replaced by their actual values during generation: - {REPOSITORY} is the repository (like microsoft/AL-Go) - {VERSION} is the version of the release - {RELEASENOTES} are the release notes of the release - {INDEXTEMPLATERELATIVEPATH} is the path of the index template ## New Action: BuildALDoc New action, which builds the ALDoc documentation for the apps in the .artifacts folder and places it in .aldoc/_site It includes the projects specified in ALDoc.Projects (or all if not specified) and excludes the projects from ALDoc.ExcludeProjects. It uses ALDoc.Header, ALDoc.Footer when invoking docfx. It uses ALDoc.DefaultIndexMD as index.md for the reference docs and ALDoc.DefaultReleaseMD as index.md for reference docs for released versions. The action also generates reference documentation for a number of prior releases (determined by setting ALDoc.MaxReleases) and adds those to the documentation site as well (under releases/version) ## Modified Workflow: CI/CD New job added: Deploy ALDoc documentation, invoked if ALDoc.ContinuousDeployment is true. If ALDoc.DeployToGitHubPages is true (which is default) the workflow automatically deploys to GitHub pages (if supported by the SKU) ## New Workflow: Deploy Reference Documentation If ALDoc.ContinuousDeployment is false (or if you want to redeploy) you can invoke this workflow to manually generate and publish the reference documentation. If ALDoc.DeployToGitHubPages is true (which is default) the workflow automatically deploys to GitHub pages (if supported by the SKU) # Try it out Update AL-Go system files with **freddydk/AL-Go@aldoc** --------- Co-authored-by: freddydk <freddydk@users.noreply.github.com> Co-authored-by: Maria Zhelezova <43066499+mazhelez@users.noreply.github.com> Co-authored-by: Alexander Holstrup <117829001+aholstrup1@users.noreply.github.com>
microsoft · Dec 5, 2023 · 39d8f99 · 39d8f99
1 parent 480d2bf
commit 39d8f99
Show file tree

Hide file tree

Showing 64 changed files with 1,749 additions and 327 deletions.
diff --git a/Actions/AL-Go-Helper.ps1 b/Actions/AL-Go-Helper.ps1
@@ -620,9 +620,21 @@ function ReadSettings {
         "environments"                                  = @()
         "buildModes"                                    = @()
         "useCompilerFolder"                             = $false
-        "PullRequestTrigger"                            = "pull_request_target"
+        "pullRequestTrigger"                            = "pull_request_target"
         "fullBuildPatterns"                             = @()
         "excludeEnvironments"                           = @()
+        "alDoc"                                         = [ordered]@{
+            "continuousDeployment"                      = $false
+            "deployToGitHubPages"                       = $true
+            "maxReleases"                               = 3
+            "groupByProject"                      = $true
+            "includeProjects"                           = @()
+            "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'

diff --git a/Actions/AddExistingApp/action.yaml b/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

diff --git a/Actions/AnalyzeTests/action.yaml b/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)