Great!!!!! I think there is general agreement that some part of the site should be generated with Antora, and I’d certainly like some collaboration. If you are interested in this, you could start by looking into Antora a bit (perhaps Antora Documentation :: Antora Docs <https://docs.antora.org/>), installing node and npm, and seeing if you can build the lates preview site I just set up (see my other latest post). To understand some of Antora’s capabilities it might be useful to look at the projects in David Jencks / Simple Examples · GitLab <https://gitlab.com/djencks/simple-examples> which are each intended to demonstrate one feature without a lot of distracting content :-)
If you like web design, the UI project is going to need some work. Another very incomplete area is organization of the pages within an Antora component. So far I just concentrated on getting all the content into grammatical asciidoc, without considering organization. If I remember correctly, the existing site has some lists of pages generated from asciidoc header attributes; nearly all the pages are in a flat directory structure. I think it would make sense to look at all the existing documentation and organize it into categories in different Antora modules or topics, and provide lists of pages in the nav that are ordered in a well-thought out arrangement. If you have any questions, please ask! Thanks, David Jencks > On Jul 15, 2020, at 5:37 PM, Willes Reis <willesr...@gmail.com> wrote: > > I have seen plenty of discussions and thoughts about evolution in tomee > site and some hard decisions to make. > But independently of the goal adopted, I'd really like to help with > something. > I like to face challenges and I have been interested in using these tools > to learn more and contribute to the organization and standardization of the > platform. > Is there a small step to get started? > > Willes Reis > > Em qua., 15 de jul. de 2020 às 12:22, David Jencks <david.a.jen...@gmail.com> > escreveu: > >> >> >>> 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 >>>> >>>> >> >>
