ALDoc support in AL-Go

[freddydk]

TO:DO

Tasks

Beta Give feedback

1. Create new Action: BuildALDoc to build reference documentation
2. Create new job in CI/CD to build and publish reference documentation
3. Create reference documentation for x versions of the apps.
4. Create new workflow for publishing ALDoc reference documentation
5. Only allow publishing reference documentation if GitHub Pages is set to GitHub Actions
6. Add release notes
7. Add documentation
8. 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

[mazhelez]

Left some non-blocking comments.

After the new github.ref_name == 'main' check for the new job in the CI/CD workflow, I'm even more convinced that a separate workflow is the better approach.

I have some doubts about the scheduling functionality of the new "Deploy Reference Documentation" workflow. Seems unlikely to build the documentation on a schedule.

Good job on the E2E tests for the new workflow.