Switch the reference documentation to Antora

[rwinch]

Migrate the asciidoc based reference documentation to Antora https://antora.org/. The new documentation site https://docs.spring.io/spring-framework/reference/ provides more structured content, an integrated search, a link to "edit this page", multiple versions with option to switch, a warning at the top of older versions, and more.

For more details on the Antora integration for Spring projects, see https://github.com/spring-io/antora-ui-spring. It is also the right place to report issues related to the user interface.

[simonbasle]

I would suggest an allow-list of exact branches to consider, rather than branches-ignore.
Similarly, I would suggest restricting the tags to something like 'v[0-9]+.[0-9]+.[0-9]+'

[rwinch]

Thanks for the feedback. I'm wondering if maintaining this list, or even ignoring gh-pages, is worth it given that the logic to decide if a workflow event is triggered is:

The following steps occur to trigger a workflow run:

1. An event occurs on your repository. The event has an associated commit SHA and Git ref.

2. GitHub searches the .github/workflows directory in your repository for workflow files that are present in the associated commit SHA or Git ref of the event.

3. A workflow run is triggered for any workflows that have on: values that match the triggering event. Some events also require the workflow file to be present on the default branch of the repository in order to run.

Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, GitHub sets the GITHUB_SHA (commit SHA) and GITHUB_REF (Git ref) environment variables in the runner environment. For more information, see "Variables."

I view the branches-ignore attribute as a redundancy since unless someone merges the workflow into a branch or tag that you want to exclude, the workflow will not be considered. Excluding gh-pages is fairly simple, but maintaining a list of tags and branches (or expression/s that does the same) to include seems unnecessary overhead given that the workflow file will not be present.

Is there a specific concern you have here?

[rstoyanchev]

I've merged the changes in for now. Let's take this as a follow-up if needed, depending on the outcome of the discussion.

[simonbasle]

Ok. No specific concern, just a habit I got.

I guess for the framework team it doesn't happen that often that a branch would be created in the original repository, although we do have a couple of leftover branches.
But I guess if such a branch was created (e.g. for an experiment) it would have the file unless if it is an orphan branch (like docs-build).

There's the if: github.repository_owner check lower in the jobs which should broadly prevent any abuse from forks, so this should be fine from that perspective.