I’m also helping Aries move off CMS to an Antora site, and I may postpone working on the TomEE site more until that is more complete and I know more what to expect.
Two things we can expect here are - a PMC vote to adopt Antora/git site publishing for parts of the site from CMS - an infra ticket to set ??? up. David Jencks > On Aug 11, 2020, at 8:52 AM, David Jencks <david.a.jen...@gmail.com> wrote: > > David Blevins and I had a long chat about the history of OpenEJB/TomEE > documentation and I have a considerably different perspective now on the best > way forward. I’d say the most fundamental shift is my realizing that even if > doing everything with Antora is the most elegant and efficient solution, it > may not be appropriate for TomEE because it involves extending the doc build > system with javascript, whereas TomEE developers are more likely to be > comfortable with java. Learning a new language in order to improve or even > understand the doc build is too big a barrier. I’m likely to continue to see > how, for instance, “marketing pages” and the tricks in the examples can be > implemented in Antora, but because I want to learn how to do those things > rather than because they are appropriate to use in TomEE. > > I think the following steps make sense: > > - versioned doc consolidation: There are now 5 copies of the “tomee” > versioned docs; one in common, and 4 identical copies done by asciidoc > includes. Looking at one of these includes, it’s not very obvious how to > edit the page, and certainly having one copy in ‘common’ is silly. So, the > “originals” should be moved to one of the versions. The obvious choices are > 7.0.x and 8.0.x. 7 might make it more obvious that changing the doc will > change all 4 versions, but development is most convenient on master, 8.0. To > make it easiest to locate the actual source, I’ll move the ‘original’ to 8.0. > I hope that there will be a period of organization and improvement of the > existing content followed by writing new content. After reorganization has > settled down it may make sense to replace the “include” copies with one or > two actual copies in the 7.0.x and 7.1.x branches so changes in master won’t > inadvertently affect older versions. > > - common doc consolidation. The pages that show up in the common component > come from two repos: tomee-site-generator and tomee-site. I don’t think it’s > a good idea to have content in the same repo as site generator code, so I’m > planning to move the content in tomee-site-generator to tomee-site. David > said something indicating that this may not be an appropriate location, so > perhaps a new repo would be appropriate…. I’ll investigate. Also, this > content includes all the stuff that was previously in CMS and not served by > the current site build. It’s apt to need a lot of editing, consolidation, > etc, and it’s possible that this entire component should not be produced by > Antora. However, at the moment, the only place all the content is accessible > for consideration is in the Antora build, so I propose we leave it there for > now, organize it, and consider what to do with it afterwards. One > possibility, since Antora deals well with multiple versions, is to have > something similar to the current common content minus the doc pages mentioned > above as a “historical content” component version with the “current common” > component version redirect to elsewhere. > > - examples. I’ve accumulated a pile of asciidoc fixes for the READMEs and > I’ll see about getting them back to the master branch. > > - source directory structure. David pointed out that the shorter the path to > the actual adoc files the more likely people are to find them…. I’ll see how > much the path can be shortened. > > - publishing. It’s very tempting to work hard to create a highly unified > site where the Antora and non-antora pieces are indistinguishable, however > that may not be the best plan here. One of the persistent problems with > documentation is that no one likes to work on it. Any complexity or > difficulty is likely to deter people from contributing. A unified site would > need a way for all the pieces of the site build to not step on each other, > which could be hard to maintain. It may well be simpler to have two sites, > one containing the front page, “marketing material”, possibly eventually the > “common” component, the examples, and the other the Antora generated docs. > This requires more investigation but the two-site approach is very attractive > as reducing “friction”. > > > Possibly this can lead quickly to actually getting the Antora portion of the > site published soon. > > Thanks, > David Jencks > > >> On Aug 10, 2020, at 1:44 PM, David Jencks <david.a.jen...@gmail.com >> <mailto:david.a.jen...@gmail.com>> wrote: >> >> The reason Antora has a separate front page is that Dan didn’t write >> asciidoctor-openblock <https://gitlab.com/djencks/asciidoctor-openblock>. >> Since I did, it’s easy to have a front page generated by Antora. He’s known >> about this possibility for at least 5 years, but never found the time or >> motivation to do it. >> >> If you have specific complaints about the front page I wrote, please air >> them rather than ignoring my request for feedback. >> >> Could you be extremely specific about what you want generated by Antora and >> what by tomee-site-generator and what by some other unnamed tool? Are there >> parts of the current antora preview site that you think should not be >> generated by Antora? (I expect to add examples to the preview shortly, but >> we can discuss that separately). >> >> thanks >> David Jencks >> >>> On Aug 10, 2020, at 1:09 PM, David Blevins <david.blev...@gmail.com >>> <mailto:david.blev...@gmail.com>> wrote: >>> >>>> On Jul 14, 2020, at 7:34 PM, David Blevins <david.blev...@gmail.com >>>> <mailto:david.blev...@gmail.com>> wrote: >>>> >>>> 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. >>> >>> I've been doing some research and have some revised thoughts on how we >>> could potentially proceed with this. >>> >>> Being terse as possible so we can try to get this out of discussion/debate >>> mode and into action mode. >>> >>> Many Antora users, including Antora.org <http://antora.org/> itself, seem >>> to use this pattern and I think it's probably the one we want. >>> >>> - https://antora.org/ <https://antora.org/> -> Built with a general >>> purpose tool (Middleman+Asciidoc) >>> - https://docs.antora.org/ <https://docs.antora.org/> -> Built with Antora >>> >>> - https://getfedora.org/ <https://getfedora.org/> -> Built with a >>> general purpose tool >>> - https://docs.fedoraproject.org/ <https://docs.fedoraproject.org/> -> >>> Built with Antora >>> >>> - http://pinot.apache.org/ <http://pinot.apache.org/> -> Built with >>> a general purpose tool >>> - https://docs.pinot.apache.org/ <https://docs.pinot.apache.org/> -> >>> Built with GitBook >>> >>> - https://www.mulesoft.com/ <https://www.mulesoft.com/> -> Built >>> with a general purpose tool >>> - https://docs.mulesoft.com/ <https://docs.mulesoft.com/> -> Built >>> with Antora >>> >>> If we did this pattern we could probably get it done by end of week: >>> >>> - https://tomee.apache.org/ <https://tomee.apache.org/> -> Built >>> with tomee-site-generator as is now >>> - https://docs.tomee.apache.org/ <https://docs.tomee.apache.org/> -> >>> Built with Antora >>> >>> We would request a new repo not connected to the CMS for >>> docs.tomee.apache.org <http://docs.tomee.apache.org/> and have David push >>> directly to it right now. David can lead that effort and just inform us on >>> how it goes. >>> >>> We would then make the "Documentation" navigation item of tomee.apache.org >>> <http://tomee.apache.org/> point to docs.tomee.apache.org >>> <http://docs.tomee.apache.org/>. We'd still move it off the CMS, but I'm >>> happy to do the lifting on that. >>> >>> I greatly prefer this approach to either 1) endlessly debating tools or 2) >>> holding up David's work any longer. >>> >>> There would still be room for debate, but that debate could happen using >>> the staging capabilities of the git-based solution. I think we'd be in an >>> overall better position to introduce more changes with everyone on equal >>> footing. >>> >>> >>> Thoughts? >>> >>> >>> -David >>> >>> >> >
