зеркало из https://github.com/microsoft/AL-Go.git
98 строки
5.6 KiB
Markdown
98 строки
5.6 KiB
Markdown
# Reference Documentation
|
||
|
||
A vital part of your development processes is reference documentation. AL-Go for GitHub supports the ALDoc tool for reference documentation generation, either continuously as part of CI/CD, manually or scheduled.
|
||
|
||
> \[!NOTE\]
|
||
> The [ALDoc tool](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/help/help-aldoc-generate-help) generates content based on the source code. Generating content based on source code has many advantages such as accuracy, 100% reflection of the current codebase, less error-prone documentation, and it saves time. The ALDoc tool generates documentation from symbolic and syntactical information, code comments, and overall application structure based on input .app file(s). The tool also generates a help site with these reference articles, sorted by the application structure, based on the provided template.
|
||
|
||
AL-Go for GitHub supports deploying the reference documentation to GitHub Pages. GitHub Pages is websites for you and your projects, hosted directly from your GitHub repository. It is also possible to deploy the reference documentation to other static HTML hosting providers, but this requires some scripting and is not included here.
|
||
|
||
## GitHub Pages
|
||
|
||
> \[!NOTE\]
|
||
> GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see [GitHub’s plans](https://docs.github.com/en/get-started/learning-about-github/githubs-plans).
|
||
|
||
Navigate to your Common repository, go to **Settings** -> **Pages** and under **Build and deployment** select **GitHub Actions** as the source.
|
||
|
||
|  |
|
||
|-|
|
||
|
||
Choose Actions, select the **Deploy Reference Documentation** workflow and click **Run workflow**
|
||
|
||
|  |
|
||
|-|
|
||
|
||
When the workflow is done, click the workflow to open workflow details and you will find a URL to your reference documentation in the deploy step. There is also an artifact called github-pages, which is the artifact deployed to the GitHub pages website. This artifact can be deployed to any other hosting provider if needed.
|
||
|
||
|  |
|
||
|-|
|
||
|
||
Clicking the link to your reference documentation reveals the website
|
||
|
||
|  |
|
||
|-|
|
||
|
||
Now, there isn't much documentation in the Common repository as the apps doesn't contain any objects, so let's repeat the above steps with Repo1 (single-project) and MySolution (multi-project) repository.
|
||
|
||
In all repositories, click the settings icon in the About section to open repository details, specify a description and check **Use your GitHub Pages website**
|
||
|
||
|  |
|
||
|-|
|
||
|
||
After this, the link to the reference documentation is available in the upper right corner of your repository landing page.
|
||
|
||
|  |
|
||
|-|
|
||
|
||
Clicking the link on the multi-project repository, in which we did a release earlier, shows that AL-Go for GitHub includes reference documentation for prior releases as well as the current main repository.
|
||
|
||
|  |
|
||
|-|
|
||
|
||
You will see the three projects as "folders" and the apps, which are built in these projects, are listed below. You will also find a **Releases** folder under which earlier versions of the apps from the repository are listed.
|
||
|
||
## Deploying the reference documentation daily
|
||
|
||
To allow daily generation of the reference documentation, modify the .github/AL-Go-Settings.json and add a setting like this:
|
||
|
||
```json
|
||
"DeployReferenceDocumentationSchedule": "0 4 * * *"
|
||
```
|
||
|
||
> \[!NOTE\]
|
||
> This will update the reference documentation every night at 4
|
||
|
||
|  |
|
||
|-|
|
||
|
||
## Deploying the reference documentation continuously
|
||
|
||
If you want to setup continuous deployment of the reference documentation, you can add this setting:
|
||
|
||
```json
|
||
"alDoc": {
|
||
"continuousDeployment": true
|
||
}
|
||
```
|
||
|
||
> \[!NOTE\]
|
||
> There are other settings in the ALDoc settings structure, which controls the generation of the reference documentation. Inspect [https://aka.ms/algosettings#aldoc](https://aka.ms/algosettings#aldoc) to see them all.
|
||
|
||
Adding this to the ALGOORGSETTINGS organizational variable causes all repositories to continuously deploy reference documentation:
|
||
|
||
|  |
|
||
|-|
|
||
|
||
But you can also add the setting to a repository settings variable called **ALGOREPOSETTINGS** or to the repository settings file **.github/AL-Go-Settings.json** if you only want to enable this for a single repository.
|
||
|
||
Running CI/CD after enabling continuous deployment reveals the **Deploy Reference Documentation** job being run and the link to the reference documentation is available in the job.
|
||
|
||
|  |
|
||
|-|
|
||
|
||
Maybe it is about time to actually explain how you create a development environment and code your app?
|
||
|
||
______________________________________________________________________
|
||
|
||
[Index](Index.md) [next](DevelopmentEnvironments.md)
|