Details
-
Improvement
-
Status: Open
-
Major
-
Resolution: Unresolved
-
None
-
None
-
None
Description
Currently the website is built from an undocumented combination of .md files from the apache CMS, files in the tomee-site-generator project, and files in the tomee project. After several days of investigation it is still totally unclear where many of the files in svnpubsub come from. Furthermore the active part of the build system, tomcat-site-generator is undocumented and misleading. (For instance, a "Source" lists a "branch", but there are no branches for 7.1.0 or 7.0.0, only tags. I haven't been able to determine how those tags are actually checked out, but through some process they are).
Antora (https://antora.org) is designed to deal well with multi-version multi-component documentation sites. Moving to an Antora-structured documentation system would immediately clarify where the website source came from, how it is structured, and how it gets generated.
Antora is written in javascript and some extensions and preprocessing will be needed. Many of the extensions are desired features for Antora, so for those maintaining custom code should not be needed long-term. Other parts (javadoc generation) of the current site generator can probably be taken over by Maven.
Two alternatives may exist for running Antora without installing node.js locally:
- Docker container. There's an "official" Antora docker container, but I think we'll need a somewhat customized version until the required extensions are accepted and released. I haven't tried this yet.
- Gitlab makes it very easy to build an Antora documentation project using CI and publish it to netlify. I expect something similar is possible at GitHub.
I've been working on this project for a couple weeks. The repositories with my work are:
- https://github.com/djencks/tomee branches antora, antora-tomee-7.0.x, and antora-tomee-7.1.x
- https://github.com/djencks/tomee-site-generator/tree/antora
- https://github.com/djencks/tomee-site/tree/antora
A preview website generated from these branches is at https://tomee-preview.s3-us-west-2.amazonaws.com/index.html
Most of the content I've been able to identify the source of is present, including a lot that is not in the current published website. Some versions are missing (primarily examples for 7.1 and 7.0). There is some content in the current website that does not appear to have any current source. I think it is left over from a previous website version and never cleaned up.