Explore migrating away from Asciidoctor

[ciscoo]

The Gradle plugin is not actively maintained with little to no activity.

Currently, there is a warning raised when building the documentation:

Task :documentation:asciidoctor
Invocation of Task.project at execution time has been deprecated. This will fail with an error in Gradle 9.0. Consult the upgrading guide for further information: https://docs.gradle.org/8.5/userguide/upgrading_version_7.html#task_project
The JavaExecSpec.main property has been deprecated. This is scheduled to be removed in Gradle 9.0. Please use the mainClass property instead. For more information, please refer to https://docs.gradle.org/8.5/dsl/org.gradle.process.JavaExecSpec.html#org.gradle.process.JavaExecSpec:main in the Gradle documentation.

This issue is meant to explore other documentation tools.

The following are strong candidates:

• VitePress
• Material for Mkdocs

The following requirements are a must have:

• Able to display Kotlin and Groovy DSL examples, ideally with a tabbed view selection.
• Able to use/integrate withproperties from the Gradle build. For example, the CXF version defined in the version catalog.

The following are nice to have:

• Versioned documentation. Currently, the documentation is published under versioned sub-directories.
• Publish documentation without Gradle Git Publish plugin. Nothing wrong with the plugin, would just like to integrate with GitHub Actions more.

[ciscoo]

4.x was finally released for the Asciidoctor Gradle Plugin, so the deprecation warnings are now gone which is nice. Still, would like to explore other documentation tools.

[ciscoo]

For the two nice to have points:

Versioned documentation is dependent on the tool being used. With the current Asciidoctor setup, versioned docs are created through subfolders and committed to a branch for GitHub Pages to use.

VitePress does not currently provide support for versioned docs (see 109). The same setup for Asciidoctor could be replicated, but the base property would need to be in sync with the versioned documentation.

Material for Mkdocs recommends using mike from the docs. From browsing GitHub, mike takes the same approach creating subfolders of the versioned docs, for example: https://github.com/airtai/faststream/tree/gh-pages

For publishing the docs without the Gradle plugin, GitHub Actions does not really support versione , instead a archive containing the docs replaces what is already deployed (see 50). So, you would need to keep each versioned docs in the main branch which isn't really nice IMO to deal with. So, I think continue using the Gradle plugin since it works well today.

[ciscoo]

Also, with VitePress (Node.js in general), can use the com.github.node-gradle.node which avoids having to have Node.js installed globally on a system.

Mkdocs requires Python installed globally.

[ciscoo]

VitePress does not support multi-region snippets which is required since the samples shown are testing. So they must be a full example in order to test, but only select regions are shown in documentation.

vuejs/vitepress#3690

[ciscoo]

Antora is another option to look at.

[ciscoo]

I like Docusaurus' stance on versioned docs:

Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.

The documentation itself for this plugin rarely, if ever changes. So this makes the versioning nice to have requirement effectively moot. It even simplifies the build for the docs since publication can be handled by upload-pages-artifact followed by deploy-pages GitHub actions.

This brings me back to VitePress or Antora.

From experimenting, VitePress was much more intuitive to get started with a simplier project structure.

Docusaurus was excluded primarily because its structure seems dated relying on babel.

[ajiho]

I am here #109 Seeing your concerns, I also encountered the same problem Have you made a decision on which tool to use so far? Perhaps docusaurus can be used first, and after the official implementation of Vitepress, version control may only be possible with Vitepress 2. x. However, before that, docusaurus can be used. What do you think?

[ciscoo]

Not yet, but I'm leaning towards VitePress, but it requires some workarounds to get project properties/values into the documentation. For example, a custom Gradle task that gets hooked in by loading the generated file. While somewhat easy to do, it was another thing to maintain whereas with Asiidoctor I could just plugin the values in using the Gradle extension. VitePress also does not support multi region snippets which could be worked around by some custom reader/generator that strips the unneeded lines and those generated files would be included in the final docs.

I'll need to experiment more by migrating this project's documentation to all approaches and compare further.

[ciscoo]

Antora works out nicely with the existing setup since it is already setup for Asciidoc, but in order to customize Antora's UI, you need to either provide a custom UI bundle or custom template (Handlebars).

I'm not interested in maintaining a dedicated UI project for Antora. I am also not interested in maintaining a HTML Handlebars template albeit the template content is minimal.

So Antora is excluded.

The remaining candidates are VitePress and Docusaurus. I previously exluded Docusaurus, but I'm going to need to take a deeper dive.

[ciscoo]

There is a small POC with VitePress that is largely working: https://github.com/ciscoo/cxf-codegen-gradle/tree/vitepress

[ciscoo]

Did a POC on Antora even though I disregarded a few days ago: https://github.com/ciscoo/cxf-codegen-gradle/tree/antora
It was quite quick to migrate once the structure was figured out, but to the further customize as mentioned above it requires writing custom HTML/JS/CSS which I think is a bit overboard for documentation site.

Docusaurus requires quite a bit of cermony just to get started with a lot of configuration that is just a bit overloaded for my likings.

The main pain point with VitePress is migrating from AsciiDoc to Markdown which isn't bad, just a mundane task.

VitePress it is.