Antora v3 release and impact on Fedora docs

Hi everyone,

(Moved from Issue with local antora docs environment - docs - Fedora Mailing-Lists)

With the new Antora v3 release, the build.sh scripts used to build the documentation no longer work due to some change I don’t understand:

$ ./build.sh
This build script is using Podman to run the build in an isolated environment.
[12:19:48.526] FATAL (antora): configuration param 'runtime.pull' not declared in the schema for /antora/site.yml (cwd: /antora, playbook: site.yml)
Add the --stacktrace option to see the cause of the error.

Running with --stacktrace gives out:

Error: invalid reference format

As this will impact everyone try to build the documentation locally with a fresh container image, should we consider updating all the build.sh scripts in the repos to reference the previous Antora container image until this is fixed?

From Antora Release Schedule :: Antora Docs, Antora 2.3.4 will be EOL in February this year which is a really fast EOL.

Should we try to move all Fedora docs to v3 ASAP? I’m not familiar with the changes required.

Thanks!

4 Likes

See build.sh: Explicitely use Antora 2.3.4 for now by travier · Pull Request #347 · coreos/fedora-coreos-docs · GitHub as example for a temporary fix if you encounter this issue.

4 Likes

I’ve done some really quick testing, and it seems like the docs should run just fine with 3.0.0.
The configuration parameter runtime.pull is deprecated since antora 2.0, and has completely been removed in 3.0.
The new name for this parameter is runtime.fetch.
Once that fixed in site.yml, the docs is building ok and I didn’t see any major regression from 2.3.4 (but again, i didn’t spend a lot of time on this).

I suggest that we upgrade the staging environment first, see how it goes, and fix what needs to be fixed from there.
See PR#178: Sync stg with prod & Upgrade to antora 3.0 - fedora-docs/docs-fp-o - Pagure.io

5 Likes

Could I get some reviews on:

Then I will update again all the PRs in PR#178: Sync stg with prod & Upgrade to antora 3.0 - fedora-docs/docs-fp-o - Pagure.io

Thanks!

3 Likes

Antora v3.0.0 has been deployed on our staging environment => Fedora Documentation :: Fedora Docs

Please let me know if you find anything broken or unusual.

3 Likes

I checked our (Server) Docs and couldn’t find “anything broken or unusual”. Obviously, no one else has found anything either. Although, with our currently rather quiet list, that may not be saying very much.

Nevertheless, maybe it’s time to activate the change in general.

I’m holding off for a bit, as I’ve found a few broken components:

Once these are fixed, we should be all set.

edit: About the Fedora Workstation Working Group, there is a redirect to https://docs.fedoraproject.org//en-US/workstation-working-group/main/ and I have no idea where it’s coming from :face_with_raised_eyebrow:

re-edit: There was an old redirect remaining on our staging environment which has now been removed by the infra team. Thanks!

1 Like

Antora v3 is now live on production :partying_face:.
Thanks for everyone involved!

1 Like

Thanks for your efforts. I just checked our server doc pages. In staging, every page has a ToC. But on the released version none. Do I have to republish the pages? (you mentioned earlier, there is no need to modify the page content).

1 Like

The new ToC is not part of antora v3 release. It’s an update to the ui-bundle (v1.02) which is not in production yet.

1 Like

Thanks, missed that “detail”