This PR should go in after https://github.com/microsoft/AL-Go/pull/955
This PR:
* Fixes all the issues found by the pre-commit hooks (by running
`pre-commit run --all-files`)
* Adds a check on future AL-Go PRs to ensure the pre-commit hooks have
been run.
---------
Co-authored-by: Freddy Kristiansen <freddy.kristiansen@microsoft.com>
# 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>
Refactor CheckForUpdates and modify all Y/N string input fields to type:
boolean in all workflows.
This PR also adds the TemplateSha to .github/AL-Go-Settings to allow for
not downloading latest version of AL-Go system files, but instead update
the existing files based on settings changes.
---------
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>
Alexander Holstrup
Freddy Kristiansen