[Evergreen-general] Automating Antora documentation builds on GitLab

[Dan Scott]

I was exploring GitLab's CI/CD (continuous integration / delivery)
functionality last night/this morning and decided to try building our
Antora-based documentation this way with the output hosted on GitLab Pages.

It works quite nicely. I've posted a rough implementation branch at
https://gitlab.com/evergreen-library-system/evergreen-library-system/-/commits/gitlab-antora-build

As you can see, it's just a couple of YAML files; .gitlab-cy.yml defines
the "pages" step, and .gitlab-antora.yml defines a custom Antora playbook
for the Docker environment. The CI/CD piece means that a new build would be
triggered by every commit.

The output is visible at
https://evergreen-library-system.gitlab.io/evergreen-library-system/docs/latest/index.html

It's nice to see the current list of build errors, such as missing
references or media files, at a glance:
https://gitlab.com/evergreen-library-system/evergreen-library-system/-/jobs/1927489146

If we decided to merge this, we would want to modify the configuration so
that it only watches a given branch (our main branch, most likely), rather
than triggering a new build for every commit  on every branch. But most of
the doc build could also be reused as an integration test to be run against
every branch / merge request. If a test fails, then the merge request gets
flagged, the errors get reported as a comment right on the branch/merge
request (instead of having to dig into the job details), and the branch
could be blocked from merging until the problem is resolved.

I'm using the Node.js npx command to avoid having to globally install the
npm modules. npx is a nice way to avoid conflicts between requirements for
different module versions at the global level and to avoid having to run
commands as root. When you prefix a command with "npx", such as "npx
antora", it searches for the command within the local project's
node_modules path instead of globally. Could be useful elsewhere in
Evergreen.

Notes:
* I updated the build process to use the just-released Antora 3 and the
corresponding Antora lunr-extension.
* I have not applied the Evergreen customizations of CSS, the header menu,
or the contact DIG message in the footer. Antora 3 has moved to
"extensions" which are lighter weight than our current approach of cloning
and tweaking the Antora default UI repository.
* In addition to the basic "does Antora build the docs without errors"
integration test, we could add a style checker like Vale (
https://gitlab.com/jdkato/vale) as another test for the documentation. Vale
can flag spelling errors (with a custom dictionary of course) and
grammatical issues like passive voice, etc.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.evergreen-ils.org/pipermail/evergreen-general/attachments/20211229/b0f09fdf/attachment.html>