You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by David Jencks <da...@gmail.com> on 2020/08/05 06:55:52 UTC
[Website-Antora] New preview
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
Posted by David Jencks <da...@gmail.com>.
> On Aug 9, 2020, at 8:49 PM, David Blevins <db...@tomitribe.com> wrote:
>
>> On Aug 9, 2020, at 8:10 PM, Willes Reis <wi...@gmail.com> 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
Posted by David Blevins <db...@tomitribe.com>.
> On Aug 9, 2020, at 8:10 PM, Willes Reis <wi...@gmail.com> 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
Posted by Willes Reis <wi...@gmail.com>.
> 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
Posted by David Jencks <da...@gmail.com>.
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 <da...@gmail.com> wrote:
>
>
>
>> On Aug 7, 2020, at 6:16 PM, David Blevins <da...@gmail.com> wrote:
>>
>>> On Aug 7, 2020, at 5:02 PM, David Jencks <da...@gmail.com> 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
Posted by Evaldo Junior <ev...@gmail.com>.
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 <da...@gmail.com>
escreveu:
>
>
> > On Aug 7, 2020, at 6:16 PM, David Blevins <da...@gmail.com>
> wrote:
> >
> >> On Aug 7, 2020, at 5:02 PM, David Jencks <da...@gmail.com>
> 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
Posted by David Jencks <da...@gmail.com>.
> On Aug 7, 2020, at 6:16 PM, David Blevins <da...@gmail.com> wrote:
>
>> On Aug 7, 2020, at 5:02 PM, David Jencks <da...@gmail.com> 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
Posted by David Blevins <da...@gmail.com>.
> On Aug 7, 2020, at 5:02 PM, David Jencks <da...@gmail.com> 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
Re: [Website-Antora] New preview
Posted by David Jencks <da...@gmail.com>.
> On Aug 7, 2020, at 4:25 PM, David Blevins <da...@gmail.com> wrote:
>
>> On Aug 7, 2020, at 3:49 PM, David Jencks <da...@gmail.com> wrote:
>>
>>> On Aug 7, 2020, at 1:47 PM, David Blevins <da...@gmail.com> wrote:
>>>
>>>> On Aug 4, 2020, at 11:55 PM, David Jencks <da...@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
Re: [Website-Antora] New preview
Posted by David Blevins <da...@gmail.com>.
> On Aug 7, 2020, at 3:49 PM, David Jencks <da...@gmail.com> wrote:
>
>> On Aug 7, 2020, at 1:47 PM, David Blevins <da...@gmail.com> wrote:
>>
>>> On Aug 4, 2020, at 11:55 PM, David Jencks <da...@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?
>>> 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
Re: [Website-Antora] New preview
Posted by David Jencks <da...@gmail.com>.
> On Aug 7, 2020, at 1:47 PM, David Blevins <da...@gmail.com> wrote:
>
>> On Aug 4, 2020, at 11:55 PM, David Jencks <da...@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. 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
Posted by David Blevins <da...@gmail.com>.
> On Aug 4, 2020, at 11:55 PM, David Jencks <da...@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 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
Re: [Website-Antora] New preview
Posted by Daniel Dias Dos Santos <da...@gmail.com>.
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.gallimore@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 <da...@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.
> >
> > 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
Posted by Jonathan Gallimore <jo...@gmail.com>.
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 <da...@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.
>
> 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