reactor
Migrate reference documentation to Antora
This PR attempts to migrate Reactor Core reference documentation to Antora, and includes the following logical commits:
- a482fbbd007eb2f96fe1748e355acb40ae5f6f63: Moved asciidoc file paths so they are compliant with Antora structure:
- 2d340c040cb21309c3174d115a320d8d244fd6f6: Refactor ascidoc adoc files to Antora. core features and advenced features are now split in multiple adoc files
- 90e86ee64cc884bb0aec5ca71515cea1b3c0f61d: Add antora yml file descritors
- 33be68a3b15becb7598a61a80dde79d361c9eca0: Adapted gradle scripts for Antora
- ad2a090b687ac6e868530b7977073697aa4427cd: Adapted the
publishCI 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 thedocs-zipartifact 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. - 2dc05700aada8f7002061a434333af2aaeffa704: 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 projectsection 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-pdfcommand, 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
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.
in the last commit https://github.com/reactor/reactor-core/pull/3806/commits/20f7d80c1a16bf81b5452cdbeb68fff2c2f54d28, added docs/build/** in the nohttp section from the main build.gradle, else the "./gradlew checkstyleNohttp" fails.
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.
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.
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.
This care should also be applied for the testing module that has a link on the site.
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.
with https://github.com/reactor/reactor-core/pull/3806/commits/d3762ab6a722495a575e867e127a0c32ca599ecb, a friendly message is now logged in case 'antora' or 'docs' tasks are used when JDK version is lower than 17.
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.
@chemicL ,
I think I have addressed your feedbacks, except the following:
monospaceformatting 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 https://github.com/reactor/reactor-core/pull/3806#discussion_r1602005716- Example titles are not prefixed with
Example N.anymore, I have created a separate issue, see https://github.com/reactor/reactor-core/pull/3806#discussion_r1603313977 - for links out in the wild that are pointing to the current documentation, I have created a separate issue, see https://github.com/reactor/reactor-core/pull/3806#issuecomment-2115986506
please have a look to my new commits, when you have time. thanks!
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.