feat(poc): experiment Antora Atlas

tbouffard commented 1 year ago

DISCLAIMER: this is a POC so it is not intended to be merged

Resources:

"How are people handling CI for individual components?" https://antora.zulipchat.com/#narrow/stream/282400-users/topic/.E2.9C.94.20How.20are.20people.20handling.20CI.20for.20individual.20components.3F

Extension source code of the site-manifest file retrieval

covers #326 complements #567

Done

The Antora Atlas extension is always enabled, so the site-manifest file is always generated.
In the preview script, enable download of the site-manifest when building the preview but not for full site and test-resources
tested the use of the site manifest stored locally or remotely (raw and gzipped) for xref validation
README: explain how the site manifest is cached
patch the Antora Atlas extension to generate logs about the execution (this should be done with regular debug logs directly in the extension). The patch is done in this repository thanks to patch-package.

Antora Atlas 1.0.0-alpha.1 requires Antora 3.2.0-alpha.2

"Rewrite import step to run during componentsRegistered event" the componentsRegistered event doesn't exist in Antora 3.1 (https://docs.antora.org/antora/3.1/extend/generator-events-reference/), so the import code is not called if not using Antora 3.2
https://gitlab.com/antora/antora-atlas-extension/-/blob/main/CHANGELOG.adoc#user-content-1-0-0-alpha-1-2022-11-08
confirmed after asking question in zulip chat: https://antora.zulipchat.com/#narrow/stream/282400-users/topic/Atlas.20extension.3A.20Antora.20required.20version.3F

Tested with the locally generated site-manifest file which is commited in df31e23c. Xref validation OK.

./build-preview-dev.bash --local-sources --type netlify --component bcd --branch 4.0
./build-preview-dev.bash --local-sources --type netlify --component bonita --branch 2023.1

Also work with the local file with GitHub action:

doc-site workflow: https://github.com/bonitasoft/bonita-documentation-site/actions/runs/5222946175/jobs/9429114559?pr=575
not tested in source content repo (bonita-doc for example). This will be done later in a new PR

Generation locally

Command: ./build-preview-dev.bash --local-sources --type netlify --use-all-repositories No download when building all and test-sources, for instance with ./build-preview-dev.bash --type netlify --use-test-sources Evaluate the generated playbook with the --only-generate-playbook CLI option

With the sources content (HEAD on 2023-06-02 around 14:30 GMT)

raw file: 1.2Mb
gzipped file: 113.8kb site-manifest_20230602_v02_full.json.gz

Tasks

[x] Do test when fetch is forced to verify that the manifest is downloaded
[x] Check with a local file
[x] Check with a remote file: we can store it on a dedicated netlify site
[x] Check the gzip mode of the json file
[x] Confirm that Atlas generates an error generated when the url cannot be fetched. Yes
[x] hack to test the usage of the file:
- [x] put in cache manually. See https://github.com/bonitasoft/bonita-documentation-site/pull/567/files
- [x] store locally and set a path in the primary-site-url AsciiDoc attribute
- [x] check that without the extension or when disabled, xref validation fails, and when it is enabled, it works
[x] How do we initiate the usage in production? We may generate and publish the manifest first but not use it at the beginning of the preview. Then, when it is in production, start using it. --> this is what we are going to do

Tasks for a new PR

When trying to use the site-manifest for xref validation

Check if we can keep Antora 3.1.4 for production build, and run another action to do xref validation with Antora 3.2.0-alpha
Test the real workflow with a branch on Bonita-doc with a bad xref link
Workflow of the repository content. Handle the xref validation in a dedicated workflow? rework the existing build site action ?
Provide explanations in the README
- about the partial builds done by the "preview" mode like https://github.com/spring-projects/spring-security/tree/docs-build#partial-builds
- about XREF validation like in https://github.com/couchbase/docs-site/pull/503/files#diff-1194561cbea346acb1bea37d81fdf5c70def982dcbb0c64eca2a96bc51941124R85

github-actions[bot] commented 1 year ago

🎊 PR Preview ab404b92327dda533f321df179647caeabeca7fd has been successfully built and deployed to https://bonitasoft-bonita-documentation-site-test-pr-575.surge.sh

:clock1: Build time: 0.013s

_{🤖 By surge-preview}

github-actions[bot] commented 1 year ago

🎊 PR Preview ab404b92327dda533f321df179647caeabeca7fd has been successfully built and deployed to https://bonitasoft-bonita-documentation-site-site-pr-575.surge.sh

:clock1: Build time: 0.015s

_{🤖 By surge-preview}