There’s also going to be updating the content to include any changes since february or march when I last worked on this.
> On Jul 15, 2020, at 6:16 PM, David Jencks <david.a.jen...@gmail.com> wrote: > > 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 >> <mailto: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 >> <mailto:david.a.jen...@gmail.com>> >> escreveu: >> >>> >>> >>>> On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore < >>> jonathan.gallim...@gmail.com <mailto: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 >>>> <mailto:david.blev...@gmail.com>> >>>> wrote: >>>> >>>>> Attempting to combine a few threads. >>>>> >>>>> - https://github.com/apache/tomee/pull/670#issuecomment-658452277 >>>>> <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 >>> >>> <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 >>>>> >>>>> >>> >>> >
