I’ve: - started an Antora UI bundle project for TomEE: tomee-antora-ui <https://github.com/djencks/tomee-antora-ui> It’s already built, but if you want to build it yourself, clone it, run npm i, and gulp. In order to track what is changed from the default UI, I used my slightly experimental UI builder. If we want to proceed on this path I can release it to npm; right now it’s in my space on AWS.
I set header/footer colors/images to match the existing site and removed the cruft from the header. I didn’t try to match header/footer content with the existing site since I think it needs to be rethought for Antora. - started an Antora playbook project for TomEE: tomee-antora <https://github.com/djencks/tomee-antora> To build this, clone it, and run npm run clean-build. The site will be at build/site. I have not yet provided a maven project to run this. I removed the examples from what was previously in the Antora site. The results are visible at https://tomee-preview.s3-us-west-2.amazonaws.com/common/contribute.html <https://tomee-preview.s3-us-west-2.amazonaws.com/common/contribute.html> (a somewhat arbitrary start page). Since an AWS bucket isn’t a web server or a local file system, there are some strange things happening for some links. Comments: - In order to combine the playbook project with tomee-site-generator, I think tomee-site-generator needs to become a multi-module reactor maven project. Let’s make sure that is actually the most sensible approach before proceeding. - I believe this preview includes all of what I think people have been describing as the non-example non-doc content. I think this includes all the stuff previously buried in secret in, mostly, markdown and html in the CMS. IIUC there’s some objection to this being in the Antora part of the site. I would like a clear explanation of what is better for this to be non-Antora content. - IIRC the content for 7.0, 7.1, and 8 is identical (there might be slight differences, of a couple of pages). I’d suggest that since there is not enough interest to maintain the site at a high level, this be collapsed to one version. Small differences can be pointed out with “since 8.0” etc. If in the future new docs for 9.0 are actually written, that would be a good time to add another version. - I haven’t yet considered how this might be combined with non-Antora parts of the site. I pointed out a few messages ago that at least the Antora part can easily use ASF infrastructure to publish to the appropriate git repo. - I haven’t made any attempt to set up reasonable navigation in the site. I think all pages are present in navigation, but wouldn’t promise anything. I think this may relate to the “what needs to be generated” discussion. I think it would be really great if this could get enough attention so that we can end up with a new site soon. Thanks! David Jencks > On Jul 15, 2020, at 8:22 AM, David Jencks <david.a.jen...@gmail.com> wrote: > > > >> On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore >> <jonathan.gallim...@gmail.com> wrote: >> >>> I recommend we first eliminate the Apache CMS so we have a hands-free >> setup. Then I recommend we make it so the `tomee-site-generator` maven >> project is the thing that kicks off and runs Antora. >> >> Sounds good to me. >> >>> I seriously don't care what we use for them as the majority of the issues >> are content, not tool. If we need to rollout a tool to motivate people to >> pay attention to the content, let's do it. As long as everything remains >> in Asciidoc we are free to switch at any time, so there's no harm in giving >> it a try. >> >> I agree. I recall there's been some discussion about the navigation >> hierarchy and splitting stuff into "admin" and "developer", and I don't >> think that went anywhere. If we have good content, then the right >> structure will follow. Some way of enumerating what we have so we can >> identify gaps, and review content feels like a potential starting point. >> Seeing what we have on the "old" site that isn't on the "new" site could be >> interesting - if I search for something, I usually get a page from the >> "old" site. >> > > AFAIK I’ve found all the “old content”, translated it to Asciidoc, and > included it in the preview Antora site. > > David Jencks >> Jon >> >> On Wed, Jul 15, 2020 at 3:35 AM David Blevins <david.blev...@gmail.com> >> wrote: >> >>> Attempting to combine a few threads. >>> >>> - https://github.com/apache/tomee/pull/670#issuecomment-658452277 >>> >>> Antora-based website progress >>> - >>> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E >>> >>> The short version is there was doubt as to if the project was willing to >>> consider using Antora. Cesar's feedback is closest to mine: >>> >>>> - Keep current tomee-site generator as the main content and website >>> layout >>>> - Once set up as a production-ready instance, keep the Antora setup for >>>> the project documentation. This means that the current website link: >>>> https://tomee.apache.org/docs.html will be redirected to the Antora >>>> awesomeness UI. >>>> >>>> keep Antora usage for what it was made for, documentation. Keep JBake >>> for the static website layout and content. >>> >>> I would simply amend that to "Keep JBake for the static website layout and >>> content [and examples.]" >>> >>> I'm very in love with the examples and never was too happy when we >>> switched to JBake and lost the features I had added to supply javadoc >>> links, build instructions and in some cases provide an auto-generated pages >>> for them. We're finally getting those features back into the fold and >>> there are some other cool things I'd like to do such as adding >>> contributor's faces to each example, cross-linking javadoc and examples. >>> >>> Our main docs, however, are a complete mess. >>> >>> I seriously don't care what we use for them as the majority of the issues >>> are content, not tool. If we need to rollout a tool to motivate people to >>> pay attention to the content, let's do it. As long as everything remains >>> in Asciidoc we are free to switch at any time, so there's no harm in giving >>> it a try. >>> >>> I think there are two gaps we need to understand to have a better >>> conversation about using Antora >>> >>> - Eliminating the Apache CMS from our lives. This is the biggest blocker >>> to any true progress. The only reason our site doesn't automatically >>> update now is because we're using the Apache CMS which has a manual publish >>> step that takes about an hour of machine time and periodic manual >>> checking/poking during that time. >>> >>> - Understanding `tomee-site-generator` isn't an enemy to Antora and >>> doesn't need to die or be eliminated. Among other things, we use it to >>> generate asciidoc content when and where we can. It will most likely need >>> to run just before Antora. Antora would be building some mix of manually >>> created docs and some generated docs. If Antora is not capable of >>> committing generated files to git, then `tomee-site-generator` is where we >>> would do that work. >>> >>> I recommend we first eliminate the Apache CMS so we have a hands-free >>> setup. Then I recommend we make it so the `tomee-site-generator` maven >>> project is the thing that kicks off and runs Antora. >>> >>> >>> Thoughts? >>> >>> >>> -- >>> David Blevins >>> http://twitter.com/dblevins >>> http://www.tomitribe.com
