Migrate 2.x website to Antora

[vy]

This PR migrates the asciidoctor-maven-plugin-based current website in 2.x to Antora with several other improvements.

Rationale

Developers love AsciiDoc, but asciidoctor-maven-plugin falls short on addressing our needs to build a website from ~70 AsciiDoc files. In particular, the navigation (creating an overarching menu, breadcrumbs, etc.) is problematic; there is no easy way to tell the user at which level of the hierarchy they are standing at. Antora, the de facto offline site generator for AsciiDoc, address all these shortcomings and more.

Deliverables

This PR implements the following deliverables

1. Website is migrated to Antora
2. All Javadoc links are fixed
3. All inter-page links are fixed
4. All AsciiDoc and Antora warnings are fixed (that is, since all inter-page links are migrated to xref, they are checked as a part of the site goal!)
5. All unused src/site files are removed
6. Added navigation for the in-page sectioning, i.e., Table-of-Contents (this wasn't possible when using maven-site-plugin)
7. Auto-generated release notes is re-worked to avoid cluttering the Git history. Now it only runs during the pre-site phase and outputs to target/generated-site instead. That is, compiled src/changelog will not be dumped to src/site anymore.
8. Auto-generated constants.adoc is directed to target/generated-site too (similar to release notes explained above)
9. log4j-docgen-asciidoctor-extension is ported to JavaScript to work as a Asciidoctor.js extension (since that is what Antora uses)
10. No web server is needed to view the generated website anymore, you can instead simply open target/site with your browser

Review kit

Don't be put down by the amount of changed files. Many are either removed (_release_notes, src/site/resources/css, etc.) or slightly changed. Once you start scrolling down the changes, you will encounter the meat.

How to build and view the website?

# `compile` goal is necessary to generate `log4j-docgen` plugin descriptors to `/target/plugin-descriptors`.
# We use these descriptors to generate
# 1. the plugin reference page of manual
# 2. `/target/log4j-config.xsd` covering all plugins
./mvnw clean install -DskipTests

# Build the website
./mvnw site

# To view the generated website, simply open `/target/site` with your browser – no local web server is needed.

[ppkarwasz]

LGTM

[vy]

@garydgregory shared some remarks in Slack. I will address them here.

I get a 404 for the API and Implementation Javadocs.

Right. Fixed in 391e4ce.

The MongoDB page linked from the left-hand menu is missing all the information from the current site. There is no MongoDB 3 either. This makes me wonder what else is missing.

It is not missing any. It has the identical content that we have today: https://web.archive.org/web/20231225134825/https://logging.apache.org/log4j/2.x/log4j-mongodb4.html

If you are looking for the one in Manual > Appenders > NoSQLAppenderMongoDB4, it is still there.

JMS Appender is… where? OMG, all the Appenders are ALL buried on ONE page: plugin-reference. Yikes. I expect to see a left-hand menu item for each Appender, Layout, and so on, just like the current site.

Gary, I think you have a misunderstanding. Let me try to clarify certain things.

1. Components [left] menu in Antora is identical to the one we have today. You can browse to our current website (see the Components menu section on left?) and compare it yourself. If you find a difference, I would be happy to correct them.
2. We still have hand-written pages for appenders, layouts, filters, etc. in the manual. They are exactly at their same URL, nothing changed.
3. Plugin reference, as it is stated at the beginning of that page, is Javadoc-on-steroids. Instead of a fully-blown Javadoc of individual modules, it combines all modules and only exposes plugin-related information and nothing else. Right now, we have a Javadoc in FooAppender.java and a section for Foo appender in appenders.adoc. Plugin reference enables us to consolidate this information in one place: Javadoc of FooAppender. This not only helps with avoiding to duplicate the documentation effort, but also captures the configuration parameters precisely right from the sources. No more "Oh, source code actually has a timeoutMillis field, but it is incorrectly documented as timeout", or "Oh, there is actually a timeoutMillis field the user is asking for, but it is not even documented", etc.

Based on the above, IMO, you don’t need both a separate Manual and a Plugin Reference as siblings in the left-hand menu. A reference should be IN a manual.

Yes, and no. Plugin reference is generated from the source code. It might not contain the most easy-to-understand introduction. OTOH, manual is hand-written. @ppkarwasz and my long-term plan is to link to plugin reference from manual, instead of duplicating the content there. For instance, manual should not explain the configuration options of PatternLayout, instead give a brief explanation, share some use cases, examples, etc., and point to the plugin reference for details.

Regardless, I should still be able to drill down the left-hand menu for all features.

2.x-docgen-antora structure is identical to what we have today. We are not worsening the situation. If you think it can be improved, sure, please go ahead. But I don't find this a blocker for this particular PR.

The red styling for code is bad IMO. For me read == error. No IDEs I know use red code Strings for example.

Replaced it with the green IntelliJ IDEA uses in 4701171.

It’s a bummer that the left hand side menu tree is always redrawn as (mostly?) collapsed, I want to leave the nodes I opened open!

Agreed. That is a styling issue, and I prefer to tackle that later on.

It’s a bit odd to have a top-level menu item called “Get”, instead of “Download”.

Yes, because I wanted it to contain the following sub-menus:

• Download
• Runtime dependencies
• Release notes

Since, there is already a Download, I cannot call it Download. If you have a better suggestion, please say so.

Sometimes XML is styled, sometimes it is not (the FAQ page for example)

Right. This is due to the fact that the original source (Markdown, XDoc, etc.) was not indicating the language. I fixed whatever I can find in 234ac80.

“Internal components” is not good, I would say that one is not supposed to use “Internal components”, a better name might be “Log4j components” or “Self-hosted components” (kinda lame)

Improved the navigation in 205f617.