Re: [Website-Antora] New preview

[David Jencks]

> On Aug 9, 2020, at 8:49 PM, David Blevins  wrote:
> 
>> On Aug 9, 2020, at 8:10 PM, Willes Reis  wrote:
>> 
>>> I’m not sure supplying identical copies of the documentation  that claim
>>> to be for different versions is entirely desirable.  Presumably we need two
>>> copies for javax/jakarta, but I’m not sure the one in tomee-site (from CMS)
>>> or the identical 7.0, 7.1, and 8.0 versions are truly essential.
>>> 
>>> Next I may look into the examples. IIUC the java source for them is going
>>> to remain as javax for the foreseeable future.  I think that means that the
>>> README’s should also remain javax-only. Among other things this should
>>> enable easy inclusion of source-code snippets and avoid confusion when the
>>> doc says jakarta and the source says javax.
>>> 
>>> I suggested earlier that there’s no need for more than one version of the
>>> examples.  I haven’t changed my mind on this and although someone didn’t
>>> seem to like the idea, I didn’t see any arguments why having more than one
>>> version was a good idea.  Since IMO the largest problem with the docs site
>>> is that there’s too much outdated useless and wrong content, and it’s
>>> nearly totally disorganized, I think reducing the size will make everything
>>> else easier.
>>> 
>> 
>> I agree with David Jencks.
>> For sake of organization, I would like to suggest that we keep the
>> documentations isolated by branches, where each branch is a documentation
>> version (7.0.x, 7.1.x, 8.x and 9.x). Therefore, old docs will be
>> kept, while newly created ones evolve, beyond being compatible with
>> Antora's source repositories through branches.
> 
> I'd agree with that as well and it's what we currently have.  I get the 
> impression this is what David points out as a problem.
> 
> We historically have had one base of documentation that applied to all 
> versions.  It's only been in the last year that we've attempted to branch the 
> documentation as described.  I'm the only one who put any effort into it, so 
> it didn't go far.  I do think that's the right long-term approach, but I am 
> sympathetic to the argument with the documentation in the shape it's in we 
> perhaps branched too early.
> 
> I could be on board for focusing on one branch for a while with the plan to 
> return to branching once we get something we like.
> 
> As we have done one doc-base for all the versions over 19 of the last 20 
> years I wouldn't be willing to make that the permanent plan.  A major problem 
> with it is no one deletes anything because "maybe it applies to an older 
> version."  When Romain created the JBake setup he included only a subset of 
> the documentation in an attempt to fix that problem.  The way he did it ended 
> up creating new problems as much of those documents still applied, but I 
> understand what he was trying to solve.
> 

I didn’t notice any differences between any of the doc versions in february 
except fairly different bad attempts to translate from markdown to asciidoc.  
IIRC some pages disappeared but I didn’t see any content updates in the 
versioned docs.

I think it would be a really good idea for someone (hopefully someone more 
familiar with TomEE than me) to spend some time and organize the existing docs 
by hand.  To me, the current “sort by tag” approach is an admission that the 
docs are incoherent and will stay that way.  One way this might work would be 
to copy the “originals” from common to 7.0.x, then organize them there, and 
then propagate the organization to include stubs in the other versions, 
removing the copy from common.  I suppose it might be possible to write a 
script to produce an include stub matching every “original” in all the copied 
versions, in which case we could start by moving the “originals” from common to 
7.0.x.

David Jencks


> 
> 
> -David

Re: [Website-Antora] New preview

[David Blevins]

> On Aug 9, 2020, at 8:10 PM, Willes Reis  wrote:
> 
>> I’m not sure supplying identical copies of the documentation  that claim
>> to be for different versions is entirely desirable.  Presumably we need two
>> copies for javax/jakarta, but I’m not sure the one in tomee-site (from CMS)
>> or the identical 7.0, 7.1, and 8.0 versions are truly essential.
>> 
>> Next I may look into the examples. IIUC the java source for them is going
>> to remain as javax for the foreseeable future.  I think that means that the
>> README’s should also remain javax-only. Among other things this should
>> enable easy inclusion of source-code snippets and avoid confusion when the
>> doc says jakarta and the source says javax.
>> 
>> I suggested earlier that there’s no need for more than one version of the
>> examples.  I haven’t changed my mind on this and although someone didn’t
>> seem to like the idea, I didn’t see any arguments why having more than one
>> version was a good idea.  Since IMO the largest problem with the docs site
>> is that there’s too much outdated useless and wrong content, and it’s
>> nearly totally disorganized, I think reducing the size will make everything
>> else easier.
>> 
> 
> I agree with David Jencks.
> For sake of organization, I would like to suggest that we keep the
> documentations isolated by branches, where each branch is a documentation
> version (7.0.x, 7.1.x, 8.x and 9.x). Therefore, old docs will be
> kept, while newly created ones evolve, beyond being compatible with
> Antora's source repositories through branches.

I'd agree with that as well and it's what we currently have.  I get the 
impression this is what David points out as a problem.

We historically have had one base of documentation that applied to all 
versions.  It's only been in the last year that we've attempted to branch the 
documentation as described.  I'm the only one who put any effort into it, so it 
didn't go far.  I do think that's the right long-term approach, but I am 
sympathetic to the argument with the documentation in the shape it's in we 
perhaps branched too early.

I could be on board for focusing on one branch for a while with the plan to 
return to branching once we get something we like.

As we have done one doc-base for all the versions over 19 of the last 20 years 
I wouldn't be willing to make that the permanent plan.  A major problem with it 
is no one deletes anything because "maybe it applies to an older version."  
When Romain created the JBake setup he included only a subset of the 
documentation in an attempt to fix that problem.  The way he did it ended up 
creating new problems as much of those documents still applied, but I 
understand what he was trying to solve.


-David

Re: [Website-Antora] New preview

[Willes Reis]

> I’m not sure supplying identical copies of the documentation  that claim
> to be for different versions is entirely desirable.  Presumably we need two
> copies for javax/jakarta, but I’m not sure the one in tomee-site (from CMS)
> or the identical 7.0, 7.1, and 8.0 versions are truly essential.
>
> Next I may look into the examples. IIUC the java source for them is going
> to remain as javax for the foreseeable future.  I think that means that the
> README’s should also remain javax-only. Among other things this should
> enable easy inclusion of source-code snippets and avoid confusion when the
> doc says jakarta and the source says javax.
>
> I suggested earlier that there’s no need for more than one version of the
> examples.  I haven’t changed my mind on this and although someone didn’t
> seem to like the idea, I didn’t see any arguments why having more than one
> version was a good idea.  Since IMO the largest problem with the docs site
> is that there’s too much outdated useless and wrong content, and it’s
> nearly totally disorganized, I think reducing the size will make everything
> else easier.
>

I agree with David Jencks.
For sake of organization, I would like to suggest that we keep the
documentations isolated by branches, where each branch is a documentation
version (7.0.x, 7.1.x, 8.x and 9.x). Therefore, old docs will be
kept, while newly created ones evolve, beyond being compatible with
Antora's source repositories through branches.

Willes.

Re: [Website-Antora] New preview

[David Jencks]

I’ve rebased my branches on current work, added 9.0 docs and implemented 
javax/jakarta via an attribute, and pushed the preview.

You can see the javax/jakarta at work by looking at different versions of 
https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/9.0/jpa-concepts.html#_valid_resource_local_unit_usage

I think a few pages got added to explain 9.0 but I don’t think they are in the 
right place in any of my branches.  Could someone point me to all the new pages?

I asked about this in perhaps february with no response, but I’ll try again 
since the situation is now 25% worse.

With the exception of a few pages getting dropped as time went on, there are 
now 5 identical copies of every page in the docs component.  The original is in 
tomes-site, where I found it.  In order to prevent the sort of unintended drift 
that plagues the current site, the other copies are all made to be identical  
with include stubs, like this:

include::{common-vc}::page$unix-daemon.adoc[]

I’m not sure supplying identical copies of the documentation  that claim to be 
for different versions is entirely desirable.  Presumably we need two copies 
for javax/jakarta, but I’m not sure the one in tomee-site (from CMS) or the 
identical 7.0, 7.1, and 8.0 versions are truly essential.

Next I may look into the examples. IIUC the java source for them is going to 
remain as javax for the foreseeable future.  I think that means that the 
README’s should also remain javax-only. Among other things this should enable 
easy inclusion of source-code snippets and avoid confusion when the doc says 
jakarta and the source says javax.

I suggested earlier that there’s no need for more than one version of the 
examples.  I haven’t changed my mind on this and although someone didn’t seem 
to like the idea, I didn’t see any arguments why having more than one version 
was a good idea.  Since IMO the largest problem with the docs site is that 
there’s too much outdated useless and wrong content, and it’s nearly totally 
disorganized, I think reducing the size will make everything else easier.

BTW if anyone wants to try editing asciidoc I recommend using intellij tools 
with the asciidctor plugin.  It’s fairly Antora-aware and is by far the best 
tool I’ve found.  IDEA CE works fine for this.

David Jencks


> On Aug 7, 2020, at 10:56 PM, David Jencks  wrote:
> 
> 
> 
>> On Aug 7, 2020, at 6:16 PM, David Blevins  wrote:
>> 
>>> On Aug 7, 2020, at 5:02 PM, David Jencks  wrote:
>>> 
>>> 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.
>> 
>> Do you have a link on the editing capabilities?
> 
> As far as I know no one has ever done this, and as I said I think it’s a 
> really bad idea.  However, Antora is flexible enough so this is possible.
> 
> IMO magic is really bad news in something like a website that no one is 
> really interested in dedicating themselves to.  Any time you have something 
> happening that is the least bit non-standard and non-obvious you dramatically 
> increase the barriers to contribution and maintenance.  Maven is sort of 
> awful, but it’s fairly consistent, and it pretty much brought about a 
> revolution in build systems by a great deal of transparency and consistency.  
> I’m going to argue really strongly against any solution that isn’t entirely 
> visible from the source.  The two solutions I know of are two copies of the 
> docs, with the EE prefix hardcoded, and one copy with the prefix as an 
> attribute, i.e. asciidoctor “variable”.
> 
> Lets look for a solution that is completely visible in the adoc source.  I 
> think an ee prefix attribute will do that, lets try it.
> 
>> 
>> Recommended or not, is it possible to do either of the last two and what 
>> would that look like?
> 
> It would look like incomprehensible magic, and no one would be able to figure 
> out how the result was obtained.  At least I wouldn’t be able to if I stepped 
> away for a week.
> 
>> 
>>> 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.
>> 
>> We can certainly take a look.  Even if the feature doesn't get used for this 
>> problem doesn't mean learning about it is bad -- we may see another valuable 
>> way to use it.
>> 
>> In terms of commit hooks, if I had to chose between writing tool/script to 
>> force a developer to do something or writing a tool/script to do it for 
>> them, I'll always favor the latter if that's possible.
> 
> Well, the commit hook might replace either of ‘javax’ or ‘jakarta’ with 
> {ee-prefix}.  I imagine there would need to be a way to use the other prefix 
> in a particular document.  That could be another 2 attributes.
> 
> David Jencks
> 
>> 
>> 
>> -David
>> 
> 

Re: [Website-Antora] New preview

[Evaldo Junior]

David, this site is very beautiful, the art is pretty coll, a little
different.


Evaldo Junior


Em sáb., 8 de ago. de 2020 às 02:57, David Jencks 
escreveu:

>
>
> > On Aug 7, 2020, at 6:16 PM, David Blevins 
> wrote:
> >
> >> On Aug 7, 2020, at 5:02 PM, David Jencks 
> wrote:
> >>
> >> 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.
> >
> > Do you have a link on the editing capabilities?
>
> As far as I know no one has ever done this, and as I said I think it’s a
> really bad idea.  However, Antora is flexible enough so this is possible.
>
> IMO magic is really bad news in something like a website that no one is
> really interested in dedicating themselves to.  Any time you have something
> happening that is the least bit non-standard and non-obvious you
> dramatically increase the barriers to contribution and maintenance.  Maven
> is sort of awful, but it’s fairly consistent, and it pretty much brought
> about a revolution in build systems by a great deal of transparency and
> consistency.  I’m going to argue really strongly against any solution that
> isn’t entirely visible from the source.  The two solutions I know of are
> two copies of the docs, with the EE prefix hardcoded, and one copy with the
> prefix as an attribute, i.e. asciidoctor “variable”.
>
> Lets look for a solution that is completely visible in the adoc source.  I
> think an ee prefix attribute will do that, lets try it.
>
> >
> > Recommended or not, is it possible to do either of the last two and what
> would that look like?
>
> It would look like incomprehensible magic, and no one would be able to
> figure out how the result was obtained.  At least I wouldn’t be able to if
> I stepped away for a week.
>
> >
> >> 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.
> >
> > We can certainly take a look.  Even if the feature doesn't get used for
> this problem doesn't mean learning about it is bad -- we may see another
> valuable way to use it.
> >
> > In terms of commit hooks, if I had to chose between writing tool/script
> to force a developer to do something or writing a tool/script to do it for
> them, I'll always favor the latter if that's possible.
>
> Well, the commit hook might replace either of ‘javax’ or ‘jakarta’ with
> {ee-prefix}.  I imagine there would need to be a way to use the other
> prefix in a particular document.  That could be another 2 attributes.
>
> David Jencks
>
> >
> >
> > -David
> >
>
>

Re: [Website-Antora] New preview

[David Jencks]

> On Aug 7, 2020, at 6:16 PM, David Blevins  wrote:
> 
>> On Aug 7, 2020, at 5:02 PM, David Jencks  wrote:
>> 
>> 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.
> 
> Do you have a link on the editing capabilities?

As far as I know no one has ever done this, and as I said I think it’s a really 
bad idea.  However, Antora is flexible enough so this is possible.

IMO magic is really bad news in something like a website that no one is really 
interested in dedicating themselves to.  Any time you have something happening 
that is the least bit non-standard and non-obvious you dramatically increase 
the barriers to contribution and maintenance.  Maven is sort of awful, but it’s 
fairly consistent, and it pretty much brought about a revolution in build 
systems by a great deal of transparency and consistency.  I’m going to argue 
really strongly against any solution that isn’t entirely visible from the 
source.  The two solutions I know of are two copies of the docs, with the EE 
prefix hardcoded, and one copy with the prefix as an attribute, i.e. 
asciidoctor “variable”.

Lets look for a solution that is completely visible in the adoc source.  I 
think an ee prefix attribute will do that, lets try it.

> 
> Recommended or not, is it possible to do either of the last two and what 
> would that look like?

It would look like incomprehensible magic, and no one would be able to figure 
out how the result was obtained.  At least I wouldn’t be able to if I stepped 
away for a week.

> 
>> 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.
> 
> We can certainly take a look.  Even if the feature doesn't get used for this 
> problem doesn't mean learning about it is bad -- we may see another valuable 
> way to use it.
> 
> In terms of commit hooks, if I had to chose between writing tool/script to 
> force a developer to do something or writing a tool/script to do it for them, 
> I'll always favor the latter if that's possible.

Well, the commit hook might replace either of ‘javax’ or ‘jakarta’ with 
{ee-prefix}.  I imagine there would need to be a way to use the other prefix in 
a particular document.  That could be another 2 attributes.

David Jencks

> 
> 
> -David
> 

Re: [Website-Antora] New preview

[David Blevins]

> On Aug 7, 2020, at 5:02 PM, David Jencks  wrote:
> 
> 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.

Do you have a link on the editing capabilities?

Recommended or not, is it possible to do either of the last two and what would 
that look like?

> 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.

We can certainly take a look.  Even if the feature doesn't get used for this 
problem doesn't mean learning about it is bad -- we may see another valuable 
way to use it.

In terms of commit hooks, if I had to chose between writing tool/script to 
force a developer to do something or writing a tool/script to do it for them, 
I'll always favor the latter if that's possible.


-David



smime.p7s
Description: S/MIME cryptographic signature

Re: [Website-Antora] New preview

[David Jencks]

> On Aug 7, 2020, at 4:25 PM, David Blevins  wrote:
> 
>> On Aug 7, 2020, at 3:49 PM, David Jencks  wrote:
>> 
>>> On Aug 7, 2020, at 1:47 PM, David Blevins  wrote:
>>> 
 On Aug 4, 2020, at 11:55 PM, David Jencks  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 
>>  
>> 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.

yes :-)

David Jencks
> 
> 
> -David

Re: [Website-Antora] New preview

[David Blevins]

> On Aug 7, 2020, at 3:49 PM, David Jencks  wrote:
> 
>> On Aug 7, 2020, at 1:47 PM, David Blevins  wrote:
>> 
>>> On Aug 4, 2020, at 11:55 PM, David Jencks  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

Re: [Website-Antora] New preview

[David Jencks]

> On Aug 7, 2020, at 1:47 PM, David Blevins  wrote:
> 
>> On Aug 4, 2020, at 11:55 PM, David Jencks  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.  The three 
existing doc versions are all the same except for a couple pages that appear or 
disappear in different versions.

> 
>> 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.

David Jencks
> 
> 
> -David
> 

Re: [Website-Antora] New preview

[David Blevins]

> On Aug 4, 2020, at 11:55 PM, David Jencks  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 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.


-David



smime.p7s
Description: S/MIME cryptographic signature

Re: [Website-Antora] New preview

[Daniel Dias Dos Santos]

Hello David,

fantastic site, very good. :)

--

*Daniel Dias dos Santos*
Java Developer
SouJava & JCP Member
GitHub: https://github.com/Daniel-Dos
Linkedin: www.linkedin.com/in/danieldiasjava
Twitter: http://twitter.com/danieldiasjava


Em sex., 7 de ago. de 2020 às 15:46, Jonathan Gallimore <
jonathan.gallim...@gmail.com> escreveu:

> Hi David
>
> I think this looks fantastic - thank you for the update. I replied on the
> CMS retirement thread, but I'd be in favour of moving this forward.
>
> Jon
>
> On Wed, Aug 5, 2020 at 7:56 AM David Jencks 
> 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.
> >
> > 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.
> >
> > David Jencks
>

Re: [Website-Antora] New preview

[Jonathan Gallimore]

Hi David

I think this looks fantastic - thank you for the update. I replied on the
CMS retirement thread, but I'd be in favour of moving this forward.

Jon

On Wed, Aug 5, 2020 at 7:56 AM David Jencks 
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.
>
> 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.
>
> David Jencks

[Website-Antora] New preview

[David Jencks]

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.

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.

David Jencks