> On Aug 7, 2020, at 4:25 PM, David Blevins <david.blev...@gmail.com> wrote: > >> On Aug 7, 2020, at 3:49 PM, David Jencks <david.a.jen...@gmail.com> wrote: >> >>> On Aug 7, 2020, at 1:47 PM, David Blevins <david.blev...@gmail.com> wrote: >>> >>>> On Aug 4, 2020, at 11:55 PM, David Jencks <david.a.jen...@gmail.com> wrote: >>>> >>>> I updated the navigation in the preview to include all the common pages >>>> (most of which are from apache CMS and previously hard to find) and the >>>> doc pages to more closely match the existing sections. >>>> >>>> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html >>>> >>>> There are some pages I used to help generate the navigation that will be >>>> useful until things stabilize a bit more. >>>> >>>> This isn’t perfect but I think it’s in a state where it could replace the >>>> current site, with the exception of examples and javadoc. >>> >>> It's definitely a large step forward. I think there needs to be some TomEE >>> 9 presence even if the docs are a 100% copy of 8 -- i.e. you point Antora >>> at the same place as where 8 docs are getting pulled, but publish it as 9. >>> >>> Ultimately I just did a very surgical javax-to-jakarta rename on the 8 docs >>> to turn them into 9. >>> >>> Would any of these be an option we could employ? >>> >>> - post-processing: perform some final edits to the Antora-generated html >>> pages before they are committed to git >>> - pre-processing: supply a non-git source for TomEE 9 asciidoc files >>> (perhaps a zip) so we ourselves can clone/edit them and hand them to Antora >>> - hooks: does Antora have any way to allow us to hook in so we can do our >>> own prep before the generation happens? >> >> I haven’t looked into incorporating any of the doc changes since March, >> including the new TomEE 9. >> If the desired changes are that all uses of `javax` are replaced with >> `jakarta` the simplest way to do it is probably to use an attribute and >> define it as `javax` for versions < 9 and `jakarta` for versions >= 9. > > Not a complete set of concerns, but anytime someone has to remember do > something different or special to write a doc my observation is it ages very > poorly. Someone writes a script and runs it once, then it shifts to a human > task and starts to degrade. If possible, leaving it a script task run > automatically is best. > > Do you know if any of the options I mention are possible?
It’s possible to customize antora to do some sorts of editing on the fly, but I really don’t recommend it. The first two possibilities are also pretty bad ideas near Antora. I think we should take a look at the attribute idea in action before ruling it out. For one thing, it might be possible to check for non-use of the attribute by grepping for javax or jakarta, maybe in a pre-commit hook. For another, I’d guess new documentation is likely to apply only to jakarta, and if someone hardcodes jakarta there it won’t be a problem. I’m sure we can find a good solution here. > > >>>> I think that the apache git website deploy system allows a preview site, >>>> so i may investigate and see if I can get that set up. >>> >>> The Apache CMS has staging built into it (it's not great for a site of our >>> size). I asked about similar capabilities in the git-based publishing that >>> is there now and I swear there was something that allowed you to create >>> branches, but I have to go back and read those emails. >> >> There’s something about that in the asf.yml documentation here: >> https://cwiki.apache.org/confluence/display/INFRA/git+-+.asf.yaml+features >> <https://cwiki.apache.org/confluence/display/INFRA/git+-+.asf.yaml+features> >> but I haven’t tried anything related to that yet. > > That's the one. Here was the most encouraging section: > > Staging a web site preview domain > > To enable staging (live preview) of your project's web site, add a > staging entry to the site repository's .asf.yaml file. As an > example, take the imaginary yourproject-website.git with an > .asf.yaml file containing the following entry: > > staging: > profile: beta > > This would stage the current branch at > https://yourproject-beta.staged.apache.org/ > <https://yourproject-beta.staged.apache.org/> . You can add multiple > staging profiles and thus multiple branches staged for > preview. This can be helpful when doing A/B evaluations of website > contents and features. > > The ability to have many different preview sites would be an awesome enabler > of change. yes :-) David Jencks > > > -David
