I pushed another preview update. This has all the content I’ve found and except for a few pages from svn that seem to originate as html and some pages currently generated by the tomee-stie-generator I believe it has all the content that is supposed to be published.
There are about 450 errors noted by Antora building this. These are asciidoc syntax errors (mostly section level errors) and broken links. AFAICT most of the content is duplicated in 4 places: what I’m calling “common”, 8.0, 7.1, and 7.0. Fixing only one copy would be considerably quicker than comparing and fixing 4. My extremely biased opinion is that the content is approximately as good shape as the live site. There is decidedly less organization and navigation. Some pages are worse, and some are better, but it’s all presented uniformly. TomEE Documentation AWS <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html> Thanks David Jencks > On Feb 16, 2020, at 7:41 PM, David Jencks <david.a.jen...@gmail.com> wrote: > > Thanks for the more info, and I have plenty to do so no hurry, if you do have > some time some quick questions… > > is https://svn.apache.org/repos/asf/tomee/site/trunk/content > <https://svn.apache.org/repos/asf/tomee/site/trunk/content> the “same as” the > website content, so modulo .md and mdtext > html conversion I can look at it > and act like that’s the website to mimic? (also module files that have no > source) > > Is all the source from tomee-site, tomee-site-generator (including > java-generated content), and tomee? So anything not present in some format > from one of these that’s in the above svn repo can be left out? > > I’d think there must be some configuration for the Builder tomee-site-staging > but I can’t find it. > > IMO the site in any form is in such a mess that it’s hard to know where to > work first. There are tons of broken formatting, both in the existing site > and the .adoc translations, and loads of broken links that have no plausible > target. For instance one of the pages you note has > > \{include:OPENEJBx30:Singleton Beans} > > I didn’t touch that one :-) It’s a bit confusing because there’s no > OPENEJBx30 anywhere in sight, but I expect it’s supposed to refer to the same > component/version. When I get to it it will turn into a redirect. > > I’m mostly concentrating on finding all the sources, getting them into some > sort of semi-coherent structure, and fixing formatting and links that > asciidoctor complains about. I thought I was nearly done, but now there are > a lot more files :-) > > After the automatically recognized problems are fixed, examining the pages > for other problems can start. > > Thanks for the hints! > > David Jencks > > > >> On Feb 16, 2020, at 6:58 PM, David Blevins <david.blev...@gmail.com >> <mailto:david.blev...@gmail.com>> wrote: >> >> Hi David, >> >> Looks like you got there in the end. I attempted to give a heads up on that >> in my first email about the Apache CMS, but all this is complicated. Read >> this then go back and read my first email on the "Documentation Site" thread >> and hopefully it makes more sense. >> >> It's very hard to describe it with magically the right level of detail. >> Here's the way too short version. >> >> - https://github.com/apache/tomee-site-generator >> <https://github.com/apache/tomee-site-generator> spits html into here >> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/ >> <https://svn.apache.org/repos/asf/tomee/site/trunk/content/> which triggers >> this Apache CMS job >> - https://ci.apache.org/builders/tomee-site-staging >> <https://ci.apache.org/builders/tomee-site-staging> which takes any html and >> also converts the mdtext and puts them here >> - /usr/local/websites/tomee/trunk which is a private svn repo that publishes >> to here >> - http://tomee.staging.apache.org <http://tomee.staging.apache.org/> which >> can only get published if a human visits here >> - https://cms.apache.org/tomee/publish >> <https://cms.apache.org/tomee/publish> and clicks the button so all html >> (CMS and otherwise) get published here >> - http://tomee.apache.org/ <http://tomee.apache.org/> >> >> What we truly need more than a switch from Jbake to Antora is to get rid of >> the Apache CMS as that would cut out 4 of those 7 bullets leaving us with: >> >> - https://github.com/apache/tomee-site-generator >> <https://github.com/apache/tomee-site-generator> spits html into here >> - https://github.com/apache/tomee-<some-new-repo> >> <https://github.com/apache/tomee-%3Csome-new-repo%3E> which causes Apache's >> new infra to publish here >> - http://tomee.apache.org/ <http://tomee.apache.org/> >> >> Unfortunately this repo appears to be a honeypot (dead end that can only >> confuse). It used to be a mirror of >> svn.apache.org/repos/asf/tomee/site/trunk/content >> <http://svn.apache.org/repos/asf/tomee/site/trunk/content>, but it looks >> like the sync stopped about 2 years ago. >> >> >> All the work of the last 10 days or so has been on replacing the Javadoc and >> Jbake parts, which have room for improvement and Antora can definitely be >> part of that improvement, but the big win is ditching the CMS, which >> technically could happen now. >> >> Replacing the CMS probably needs its own email. >> >> I mentioned this in the first email as well; the issue you pointed out at >> the start with the badly formatted page actually wasn't an issue with Jbake. >> It was one of many legacy CMS files that wasn't fully converted out of the >> specialized Markdown format. These issues exist in your Antora prototype as >> well: >> >> - >> https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/singleton-ejb.html >> >> <https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/singleton-ejb.html> >> >> And truthfully our content issues date back to our Confluence-based website >> days as there's still a very small bit of Confluence wiki markup hanging >> around: >> >> - >> https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/local-server.html >> <https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/local-server.html> >> >> Every time we make website-tech switch, the content takes a hit and >> yesterday's content issues get rolled into the newly-created content issues. >> >> Though I see our content issues as unrelated to Jbake or Antora and are just >> plain content issues fixable with either solution, I still support some >> Antora usage. I do think we need to scale back what we're aiming at with >> Antora, however. >> >> I'll try to post on that, but it takes me hours to write emails and I still >> have a board report to do and I'm traveling in the morning, so no promises :) >> >> >> -- >> David Blevins >> http://twitter.com/dblevins <http://twitter.com/dblevins> >> http://www.tomitribe.com <http://www.tomitribe.com/> >> >>> On Feb 16, 2020, at 3:56 PM, David Jencks <david.a.jen...@gmail.com >>> <mailto:david.a.jen...@gmail.com>> wrote: >>> >>> I’ve discovered that the svn repo automatically converts .mdtext files to >>> .html, so my conclusions about how much of tomee-site are currently >>> published are wrong. I’ll redo my calculations. >>> >>> Thanks >>> David Jencks >>> >>>> On Feb 16, 2020, at 8:40 AM, David Jencks <david.a.jen...@gmail.com >>>> <mailto:david.a.jen...@gmail.com>> wrote: >>>> >>>> Hi, >>>> >>>> I’d like some verification that my conclusions about content are >>>> reasonable…. >>>> >>>> The content sources I know about are: >>>> >>>> tomee (7-8 docs and examples) >>>> >>>> tomee-site-generator (older content) >>>> >>>> tomee-site (?) >>>> >>>> My understanding is the site is published using svnpubsub, so that svn >>>> repo reflects what is actually visible on the site. >>>> >>>> After doing some set arithmetic I’ve discovered that there is no content >>>> on the current site necessarily from tomee-site; there’s a lot of overlap >>>> in content between tomee-site and tomee-site-generator, but nothing from >>>> tomee-site that is missing from tomee-site-generator is on the website. >>>> >>>> Is this reasonable? >>>> >>>> Is there anything from tomee-site not currently published that _should_ be >>>> added to the site? According to my calculations, there are about 445 >>>> pages in tomee-site that aren’t currently published. >>>> >>>> If anyone wants to study the situation, I recommend looking at my git >>>> repos where all the content I’ve found is similarly organized, and the >>>> summary in >>>> comparison.json >>>> <https://github.com/djencks/tomee/blob/antora/docs/comparison.json >>>> <https://github.com/djencks/tomee/blob/antora/docs/comparison.json>> >>>> >>>> calculated using old-new-compare.js >>>> <https://github.com/djencks/tomee/blob/antora/docs/old-new-compare.js >>>> <https://github.com/djencks/tomee/blob/antora/docs/old-new-compare.js>> >>>> >>>> There’s also quite a bit of content with no source; as I’ve mentioned >>>> before I think this is a never-cleaned-up leftover from a previous version >>>> of the site. >>>> >>>> Thanks >>>> David Jencks >>>> >>>> ps. by “necessarily” I mean all the pages in svn that could have come from >>>> tomee-site, could also have come from tomee-site-generator. I don’t >>>> really know where they actually came from, although I could probably >>>> calculate it. >>>> >>>> pps. For nitpickers: there may appear to be two unique files at >>>> tomee-site. One, security/index, is the same as security/security; I’ve >>>> provided a redirect. The other, documentation, is some sort of site index >>>> or navigation page, possibly generated. I heavily edited the version in >>>> my repo before realizing it was not needed as-is. >
