Migrate reference documentation to Antora

[pderop]

This PR attempts to migrate Reactor Core reference documentation to Antora, and includes the following logical commits:

• a482fbb: Moved asciidoc file paths so they are compliant with Antora structure:
• 2d340c0: Refactor ascidoc adoc files to Antora. core features and advenced features are now split in multiple adoc files
• 90e86ee: Add antora yml file descritors
• 33be68a: Adapted gradle scripts for Antora
• ad2a090: Adapted the publish CI in order to build the docs-zip artifact using a separate build-docs-zip job. This job uses JDK21 to generate antora doc because the antora gradle plugin requires a JDK17 compatible JVM. Once the docs-zip artifact is generated, it is then uploaded to the workflow run, and then the other deploy jobs (deploySnapshot/deployMilestone/deployRelease) can then download it to ./docs/build/distributions/ directory, and let it be included in the published artifacts. The cleanup job makes sure that the artifact is deleted from the workflow run once all deploy jobs are finished.
• 2dc0570: Updated README to explain how to generate the documentation locally.

To test this PR:

• Set the current JDK to JDK21 (or a JDK17 compatible version)
• generate the documentation:

./gradlew antora

you can browse docs/build/site/index.html

The search is not yet enabled, it will be enabled once we'll have merged this PR because it's needed to crawl the documentation using Algolia from projectreactor.io site.

To test docs.zip generation:

• Set the current JDK to JDK21 (or a JDK17 compatible version)
• then type:

./gradlew docs

it will generate docs/build/distributions/reactor-core-3.7.0-SNAPSHOT-docs.zip

To test publication:

• make sure all JDK versions are properly installed (see Trouble building the project section in the reactor core README).
• set current JDK version to JDK21.
• Run publish command:

./gradlew publishToMavenLocal

All jars should be built with proper jdk versions because toolchain is used.

• then check what is generated in your M2 repo

To test publication in two steps:

If using JDK21 as the default JDK version is really an issue, you can then publish everything in two steps:

• step 1: Set current JDK to JDK21, and only run ./gradlew docs : this will only build the docs.zip
• step 2: Set current JDK to JDK8, then run ./gradlew publishToMavenLocal, this command will pick up the docs.zip previously built in step 1 and will include it in local M2

To test PDF generation

As before, PDF are not generated by default in snapshot mode. If you want to generate a PDF, then do the following:

• first, you will need to install asciidoctor-pdf command, because the antora pdf assembler requires it:

brew install asciidoctor

• then generate antora documention + PDF:

./gradlew antora -PforcePdf

docs is generated as before in docs/build/site/index.html, but this time a PDF is also generated in ./docs/build/assembler/reactor/3.7.0/reactor-3-reference-guide.pdf

If you want to include the pdf in the docs.zip distribution file:

./gradlew docs -PforcePdf

and the pdf will be generated and included in the docs.zip:

unzip -l docs/build/distributions/reactor-core-3.7.0-SNAPSHOT-docs.zip |grep pdf
  4114787  05-03-2024 10:35   docs/reactor-core-reference-guide-3.7.0-SNAPSHOT.pdf

• you can force PDF generation also when publishing:

./gradlew publishToMavenLocal -PforcePdf
unzip -l ~/.m2/repository/io/projectreactor/reactor-core/3.7.0-SNAPSHOT/reactor-core-3.7.0-SNAPSHOT-docs.zip | grep pdf
  4114787  05-03-2024 10:37   docs/reactor-core-reference-guide-3.7.0-SNAPSHOT.pdf

as before, PDF is generated and included when releasing a RELEASE, or RC, or a MILESTONE, but not when releasing a SNAPSHOT version.

Fixes #3083

[pderop]

the previous force-push commit contains a fix in the GH action publish.yml, in order to build the docs-zip using a separate build-docs-zip job that is using JDK21. It allows the other deploy jobs (deployRelease/deploySnapshot/deployMilistone) to download it and include it in the published artifacts, but still using JDK8 as the default JDK.

[pderop]

in the last commit 20f7d80, added docs/build/** in the nohttp section from the main build.gradle, else the "./gradlew checkstyleNohttp" fails.

[chemicL]

Thanks for the updates. I'll check the generated docs now. First thing that happened was me running with JDK8:

./gradlew clean antora

FAILURE: Build failed with an exception.

* What went wrong:
Task 'antora' not found in root project 'reactor' and its subprojects.

I believe it should fail saying that JDK17+ is required instead.

[chemicL]

Running

./gradlew clean docs

I get

FAILURE: Build failed with an exception.

* What went wrong:
Task 'docs' not found in root project 'reactor' and its subprojects.

I think it should also fail with a message explaining JDK17+ is required.

[chemicL]

Keep in mind that projectreactor.io has a link to a specific section as "Choosing an Operator" that points to index.html#which-operator. After these changes it should point to apdx-operatorChoice.html.

[chemicL]

This care should also be applied for the testing module that has a link on the site.

[chemicL]

Suggested change

	link:https://github.com/reactor/reactor-core/edit/main/docs/modules/ROOT/pages/aboutDoc.adoc[Edit this Page^, role="fa fa-edit"] to xref:aboutDoc.adoc[About the Documentation].
	link:https://github.com/reactor/reactor-core/edit/main/docs/modules/ROOT/pages/aboutDoc.adoc[Edit this Page^, role="fa fa-edit"] to make changes to xref:aboutDoc.adoc[About the Documentation] page.

[pderop]

see 75f03a8

[chemicL]

The generate does not render correctly as code.

[pderop]

I cannot find a solution for the moment.
what I see is that when also generating the doc into PDF, then the generate part is rendered:

Now, I have tried to change the backquotes with "#", like this:

.Example of state-based #generate#

and generate is then rendered like this:

are you ok to go with this ? else, I think we need to address this issue later, using another PR ?

[chemicL]

I don't think the green background works. Let's see if this can be improved afterwards.

[pderop]

Have created #3813 issue to not forget about this.

[chemicL]

The link is incorrect - it should point to the section in advanced features / null-safety, not this section itself.

[pderop]

fixed in b80c9d3

[chemicL]

I don't know whether or how this can be fixed but please verify ALL the Example N. Title places in the documentation - some of them now start with the word "Example", some don't. In the current documentation all examples have the same prefix and a significant and useful number. It would be a good idea to keep that.

[chemicL]

The other problem is that the rendering of these "Example" headers don't provide a background for the monospace font and it is inconsistent with what we had and what other monospaced highlights provide.

[pderop]

I don't know whether or how this can be fixed but please verify ALL the Example N. Title places in the documentation - some of them now start with the word "Example", some don't. In the current documentation all examples have the same prefix and a significant and useful number. It would be a good idea to keep that.

The problem is that before, all example titles were indeed automatically prefixed with Example N, but I cannot find a way to re-enable this behavior.

So, before, we had few titles starting with Example word, like these ones:

.Example of Callback Hell
.Example of Reactor code equivalent to callback code
.Example of Reactor code with timeout and fallback
.Example of `CompletableFuture` combination
.Example of Reactor code equivalent to future code
.Example of state-based `generate`

which were respectively rendered like this:

Example 5. Example of Callback Hell
Example 6. Example of Reactor code equivalent to callback code
Example 7. Example of Reactor code with timeout and fallback
Example 8. Example of CompletableFuture combination
Example 9. Example of Reactor code equivalent to future code
Example 11. Example of state-based generate

So, now, for these titles, they are rendered without the Example Nprefix, but we still see the Example word, because these few examples title are starting with the Example word:

Example of Callback Hell
Example of Reactor code equivalent to callback code
Example of Reactor code with timeout and fallback
Example of CompletableFuture combination
Example of Reactor code equivalent to future code
Example of state-based generate

The other problem is that the rendering of these "Example" headers don't provide a background for the monospace font and it is inconsistent with what we had and what other monospaced highlights provide.

I suspect that this is also related to the antora-ui-projectreactor (I'm not sure).

Since for the moment, I'm unable to re-enable automatic generation of the Example N. prefix, I would prefer to address this issue in a specific new PR, if you don't mind.

[violetagg]

If you decide to make a change in additional PR, please create an issue so that we do not forget. Thanks!

[pderop]

Created the issue to not forget about: #3811

[chemicL]

This bit is supposed to be hidden

[pderop]

Fixed in b2f925c

[chemicL]

General comment around the change of structure and URIs – do you have a plan to redirect existing links to our documentation out in the wild to the new structure? E.g. https://www.canva.dev/blog/engineering/enabling-real-time-collaboration-with-rsocket/ in the section about Logs has a link to https://projectreactor.io/docs/core/release/reference/#faq.mdc which as I understand would now fail. I believe it would be worth considering a way to make some redirections to aid users in finding this content.

[pderop]

with d3762ab, a friendly message is now logged in case 'antora' or 'docs' tasks are used when JDK version is lower than 17.

[pderop]

General comment around the change of structure and URIs – do you have a plan to redirect existing links to our documentation out in the wild to the new structure? E.g. https://www.canva.dev/blog/engineering/enabling-real-time-collaboration-with-rsocket/ in the section about Logs has a link to https://projectreactor.io/docs/core/release/reference/#faq.mdc which as I understand would now fail. I believe it would be worth considering a way to make some redirections to aid users in finding this content.

in some cases, we could possibly use page-aliases attributes. but I'm afraid that for some other cases, it's won't be possible.
https://projectreactor.io/docs/core/release/reference/#faq.mdc will map to the start-page followed by #faq.mdc (https://projectreactor.io/docs/core/release/reference/aboutDoc.html#faq.mdc).

For this particular case, we need to configure some redirect mapping in Cloudflare.

I have create #3812 issue to address this problem separately.

[pderop]

@chemicL ,

I think I have addressed your feedbacks, except the following:

• monospace formatting seems to be not rendered when used in Example titles, I need your feedback about doing an alternative, or we need to address this later in a separate PR, maybe it's related to antora-ui-projectreactor. See Migrate reference documentation to Antora #3806 (comment)
• Example titles are not prefixed with Example N. anymore, I have created a separate issue, see Migrate reference documentation to Antora #3806 (comment)
• for links out in the wild that are pointing to the current documentation, I have created a separate issue, see Migrate reference documentation to Antora #3806 (comment)

please have a look to my new commits, when you have time.
thanks!

[chemicL]

@pderop Thank you for addressing the comments and creating issues for the remainder. I'm going to check the PDF now but otherwise I think all is good, so approving.

[chemicL]

Last remark: -PforcePdf does not fail if the asciidoctor command was not installed. I think it should fail the build if this option is used. I think this can be addressed in another PR.