David Jencks created TOMEE-2772:
-----------------------------------
Summary: Build website with Antora
Key: TOMEE-2772
URL: https://issues.apache.org/jira/browse/TOMEE-2772
Project: TomEE
Issue Type: Improvement
Components: Website
Reporter: David Jencks
Assignee: David Jencks
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)|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.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
