> On Aug 7, 2020, at 3:49 PM, David Jencks <[email protected]> wrote: > >> On Aug 7, 2020, at 1:47 PM, David Blevins <[email protected]> wrote: >> >>> On Aug 4, 2020, at 11:55 PM, David Jencks <[email protected]> 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? >>> 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 > 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/ . 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. -David
smime.p7s
Description: S/MIME cryptographic signature
