AL-Go/Workshop/ReferenceDoc.md

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 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.

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:

  "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:

  "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 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  next