Structure AsciiDoc website with Antora

[kriegaex]

After conversion to AsciiDoc and HTML/PDF generation build steps using Asciidoctor have been implemented and merged already as part of #76, comprehensive navigation is still missing. Yes, there is a landing page, off of which all documentation is linked, and it would work nicely both locally (unpacked docs from installer) and on the Eclipse website, but in contrast to the multi-page docs created via DocBook, there is no navigation to next or previous page and especially none to the next higher level. I.e., if a user ends up on any docs chapter via a direct link from Google, Stack Overflow or any blog, she has no easy way to navigate up to the main docs landing page or any intermediate overview page.

Therefore, one idea is to use Antora via Antora Maven Plugin to generate one integrated docs website with navigation.

This could be done before initial site publication or afterwards. The advantage of doing it before publication is that in case of URL changes caused by Antora documentation module structure, the Eclipse infra team would have to create redirects from legacy docs URLs to new ones only once. The downside would be even later publication.

• Explore options to use a single vs. several modules
• Explore options to create versioned docs and select a version via generated navigation

[kriegaex]

After some experiments on branch https://github.com/eclipse-aspectj/aspectj/tree/antora, which involed some directory restructuring, I have decided not to pursue this issue further at the moment. Talks with the Antora team about the question how to best include non-asciidoc resources into the website generation process made it clear that I would have to do more than just configure the product, but customise it, i.e. write some own code for an Antora extension. The generated docs look great with the navigation panel for the whole website on the left hand side etc., but IMO it is not worth the effort to maintain yet another piece of code somewhere, just to perfect the website. As it is now, it is OK - not as great as we would like it to be, but we have a working solution and the new docs are online at https://eclipse.dev/aspectj/doc/latest/.

Keeping the issue open for future consideration.