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 Blevins <da...@gmail.com> on 2020/07/15 02:34:54 UTC
Making Antora actionable
Attempting to combine a few threads.
- https://github.com/apache/tomee/pull/670#issuecomment-658452277
Antora-based website progress
- https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E
The short version is there was doubt as to if the project was willing to consider using Antora. Cesar's feedback is closest to mine:
> - Keep current tomee-site generator as the main content and website layout
> - Once set up as a production-ready instance, keep the Antora setup for
> the project documentation. This means that the current website link:
> https://tomee.apache.org/docs.html will be redirected to the Antora
> awesomeness UI.
>
> keep Antora usage for what it was made for, documentation. Keep JBake for the static website layout and content.
I would simply amend that to "Keep JBake for the static website layout and content [and examples.]"
I'm very in love with the examples and never was too happy when we switched to JBake and lost the features I had added to supply javadoc links, build instructions and in some cases provide an auto-generated pages for them. We're finally getting those features back into the fold and there are some other cool things I'd like to do such as adding contributor's faces to each example, cross-linking javadoc and examples.
Our main docs, however, are a complete mess.
I seriously don't care what we use for them as the majority of the issues are content, not tool. If we need to rollout a tool to motivate people to pay attention to the content, let's do it. As long as everything remains in Asciidoc we are free to switch at any time, so there's no harm in giving it a try.
I think there are two gaps we need to understand to have a better conversation about using Antora
- Eliminating the Apache CMS from our lives. This is the biggest blocker to any true progress. The only reason our site doesn't automatically update now is because we're using the Apache CMS which has a manual publish step that takes about an hour of machine time and periodic manual checking/poking during that time.
- Understanding `tomee-site-generator` isn't an enemy to Antora and doesn't need to die or be eliminated. Among other things, we use it to generate asciidoc content when and where we can. It will most likely need to run just before Antora. Antora would be building some mix of manually created docs and some generated docs. If Antora is not capable of committing generated files to git, then `tomee-site-generator` is where we would do that work.
I recommend we first eliminate the Apache CMS so we have a hands-free setup. Then I recommend we make it so the `tomee-site-generator` maven project is the thing that kicks off and runs Antora.
Thoughts?
--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
> On Jul 14, 2020, at 7:34 PM, David Blevins <da...@gmail.com> wrote:
>
> Attempting to combine a few threads.
>
> - https://github.com/apache/tomee/pull/670#issuecomment-658452277
>
> Antora-based website progress
> - https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E
>
> The short version is there was doubt as to if the project was willing to consider using Antora. Cesar's feedback is closest to mine:
>
>> - Keep current tomee-site generator as the main content and website layout
>> - Once set up as a production-ready instance, keep the Antora setup for
>> the project documentation. This means that the current website link:
>> https://tomee.apache.org/docs.html will be redirected to the Antora
>> awesomeness UI.
>>
>> keep Antora usage for what it was made for, documentation. Keep JBake for the static website layout and content.
>
> I would simply amend that to "Keep JBake for the static website layout and content [and examples.]"
>
> I'm very in love with the examples and never was too happy when we switched to JBake and lost the features I had added to supply javadoc links, build instructions and in some cases provide an auto-generated pages for them. We're finally getting those features back into the fold and there are some other cool things I'd like to do such as adding contributor's faces to each example, cross-linking javadoc and examples.
>
> Our main docs, however, are a complete mess.
>
> I seriously don't care what we use for them as the majority of the issues are content, not tool. If we need to rollout a tool to motivate people to pay attention to the content, let's do it. As long as everything remains in Asciidoc we are free to switch at any time, so there's no harm in giving it a try.
There’s a significant amount of content in markdown, that I converted to asciidoc.
>
> I think there are two gaps we need to understand to have a better conversation about using Antora
>
> - Eliminating the Apache CMS from our lives. This is the biggest blocker to any true progress. The only reason our site doesn't automatically update now is because we're using the Apache CMS which has a manual publish step that takes about an hour of machine time and periodic manual checking/poking during that time.
>
> - Understanding `tomee-site-generator` isn't an enemy to Antora and doesn't need to die or be eliminated. Among other things, we use it to generate asciidoc content when and where we can. It will most likely need to run just before Antora. Antora would be building some mix of manually created docs and some generated docs. If Antora is not capable of committing generated files to git, then `tomee-site-generator` is where we would do that work.
>
> I recommend we first eliminate the Apache CMS so we have a hands-free setup. Then I recommend we make it so the `tomee-site-generator` maven project is the thing that kicks off and runs Antora.
>
I’m confused about what you envisage here. Do you want to deploy the current site without Apache CMS? If so, what are you planning to do about the markdown content hidden away? Or do you want to plan to deploy the content using Antora? Or do you want to discuss and come up with a plan?
If we have a process for building the entire site into a directory, it’s pretty easy to use ASF infrastructure to publish it. For instance, Camel uses a Jenkinsfile to build the site, and then run this to publish it:
steps {
dir('deploy/staging') {
deleteDir()
sh 'git clone -b asf-site https://gitbox.apache.org/repos/asf/camel-website.git .'
sh 'git rm -r *'
sh "cp -R $WORKSPACE/camel-website/public/. ."
sh 'git add .'
sh 'git commit -m "Website updated to $(git rev-parse --short HEAD)"'
sh 'git push origin asf-site'
}
}
The Antora part is easy for me to set up, I’m not sure how it would relate to other parts, especially, if this isn’t done using Antora, the parts that are currently hidden in CMS in markdown.
It’s easy to run Antora from Maven, for instance Camel does it, although not for the Jenkinsfile. I’d suggest a separate maven subproject in the tomee-site-generator repo.
A larger obstacle seems to me that I doubt we’d want to use the Antora default UI as-is, so someone would have to make it more TomEE friendly. I can change colors and do some things with header/footer content, but not a whole lot more than that.
>
> Thoughts?
>
Thanks for engaging!
David Jencks
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
There’s also going to be updating the content to include any changes since february or march when I last worked on this.
> On Jul 15, 2020, at 6:16 PM, David Jencks <da...@gmail.com> wrote:
>
> Great!!!!!
>
> I think there is general agreement that some part of the site should be generated with Antora, and I’d certainly like some collaboration. If you are interested in this, you could start by looking into Antora a bit (perhaps Antora Documentation :: Antora Docs <https://docs.antora.org/>), installing node and npm, and seeing if you can build the lates preview site I just set up (see my other latest post). To understand some of Antora’s capabilities it might be useful to look at the projects in David Jencks / Simple Examples · GitLab <https://gitlab.com/djencks/simple-examples> which are each intended to demonstrate one feature without a lot of distracting content :-)
>
> If you like web design, the UI project is going to need some work.
>
> Another very incomplete area is organization of the pages within an Antora component. So far I just concentrated on getting all the content into grammatical asciidoc, without considering organization. If I remember correctly, the existing site has some lists of pages generated from asciidoc header attributes; nearly all the pages are in a flat directory structure. I think it would make sense to look at all the existing documentation and organize it into categories in different Antora modules or topics, and provide lists of pages in the nav that are ordered in a well-thought out arrangement.
>
> If you have any questions, please ask!
>
> Thanks,
> David Jencks
>
>> On Jul 15, 2020, at 5:37 PM, Willes Reis <willesreis@gmail.com <ma...@gmail.com>> wrote:
>>
>> I have seen plenty of discussions and thoughts about evolution in tomee
>> site and some hard decisions to make.
>> But independently of the goal adopted, I'd really like to help with
>> something.
>> I like to face challenges and I have been interested in using these tools
>> to learn more and contribute to the organization and standardization of the
>> platform.
>> Is there a small step to get started?
>>
>> Willes Reis
>>
>> Em qua., 15 de jul. de 2020 às 12:22, David Jencks <david.a.jencks@gmail.com <ma...@gmail.com>>
>> escreveu:
>>
>>>
>>>
>>>> On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore <
>>> jonathan.gallimore@gmail.com <ma...@gmail.com>> wrote:
>>>>
>>>>> I recommend we first eliminate the Apache CMS so we have a hands-free
>>>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>>>> project is the thing that kicks off and runs Antora.
>>>>
>>>> Sounds good to me.
>>>>
>>>>> I seriously don't care what we use for them as the majority of the
>>> issues
>>>> are content, not tool. If we need to rollout a tool to motivate people
>>> to
>>>> pay attention to the content, let's do it. As long as everything remains
>>>> in Asciidoc we are free to switch at any time, so there's no harm in
>>> giving
>>>> it a try.
>>>>
>>>> I agree. I recall there's been some discussion about the navigation
>>>> hierarchy and splitting stuff into "admin" and "developer", and I don't
>>>> think that went anywhere. If we have good content, then the right
>>>> structure will follow. Some way of enumerating what we have so we can
>>>> identify gaps, and review content feels like a potential starting point.
>>>> Seeing what we have on the "old" site that isn't on the "new" site could
>>> be
>>>> interesting - if I search for something, I usually get a page from the
>>>> "old" site.
>>>>
>>>
>>> AFAIK I’ve found all the “old content”, translated it to Asciidoc, and
>>> included it in the preview Antora site.
>>>
>>> David Jencks
>>>> Jon
>>>>
>>>> On Wed, Jul 15, 2020 at 3:35 AM David Blevins <david.blevins@gmail.com <ma...@gmail.com>>
>>>> wrote:
>>>>
>>>>> Attempting to combine a few threads.
>>>>>
>>>>> - https://github.com/apache/tomee/pull/670#issuecomment-658452277 <https://github.com/apache/tomee/pull/670#issuecomment-658452277>
>>>>>
>>>>> Antora-based website progress
>>>>> -
>>>>>
>>> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E <https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E>
>>>>>
>>>>> The short version is there was doubt as to if the project was willing to
>>>>> consider using Antora. Cesar's feedback is closest to mine:
>>>>>
>>>>>> - Keep current tomee-site generator as the main content and website
>>>>> layout
>>>>>> - Once set up as a production-ready instance, keep the Antora setup for
>>>>>> the project documentation. This means that the current website link:
>>>>>> https://tomee.apache.org/docs.html will be redirected to the Antora
>>>>>> awesomeness UI.
>>>>>>
>>>>>> keep Antora usage for what it was made for, documentation. Keep JBake
>>>>> for the static website layout and content.
>>>>>
>>>>> I would simply amend that to "Keep JBake for the static website layout
>>> and
>>>>> content [and examples.]"
>>>>>
>>>>> I'm very in love with the examples and never was too happy when we
>>>>> switched to JBake and lost the features I had added to supply javadoc
>>>>> links, build instructions and in some cases provide an auto-generated
>>> pages
>>>>> for them. We're finally getting those features back into the fold and
>>>>> there are some other cool things I'd like to do such as adding
>>>>> contributor's faces to each example, cross-linking javadoc and examples.
>>>>>
>>>>> Our main docs, however, are a complete mess.
>>>>>
>>>>> I seriously don't care what we use for them as the majority of the
>>> issues
>>>>> are content, not tool. If we need to rollout a tool to motivate people
>>> to
>>>>> pay attention to the content, let's do it. As long as everything
>>> remains
>>>>> in Asciidoc we are free to switch at any time, so there's no harm in
>>> giving
>>>>> it a try.
>>>>>
>>>>> I think there are two gaps we need to understand to have a better
>>>>> conversation about using Antora
>>>>>
>>>>> - Eliminating the Apache CMS from our lives. This is the biggest
>>> blocker
>>>>> to any true progress. The only reason our site doesn't automatically
>>>>> update now is because we're using the Apache CMS which has a manual
>>> publish
>>>>> step that takes about an hour of machine time and periodic manual
>>>>> checking/poking during that time.
>>>>>
>>>>> - Understanding `tomee-site-generator` isn't an enemy to Antora and
>>>>> doesn't need to die or be eliminated. Among other things, we use it to
>>>>> generate asciidoc content when and where we can. It will most likely
>>> need
>>>>> to run just before Antora. Antora would be building some mix of
>>> manually
>>>>> created docs and some generated docs. If Antora is not capable of
>>>>> committing generated files to git, then `tomee-site-generator` is where
>>> we
>>>>> would do that work.
>>>>>
>>>>> I recommend we first eliminate the Apache CMS so we have a hands-free
>>>>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>>>>> project is the thing that kicks off and runs Antora.
>>>>>
>>>>>
>>>>> Thoughts?
>>>>>
>>>>>
>>>>> --
>>>>> David Blevins
>>>>> http://twitter.com/dblevins
>>>>> http://www.tomitribe.com
>>>>>
>>>>>
>>>
>>>
>
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
Great!!!!!
I think there is general agreement that some part of the site should be generated with Antora, and I’d certainly like some collaboration. If you are interested in this, you could start by looking into Antora a bit (perhaps Antora Documentation :: Antora Docs <https://docs.antora.org/>), installing node and npm, and seeing if you can build the lates preview site I just set up (see my other latest post). To understand some of Antora’s capabilities it might be useful to look at the projects in David Jencks / Simple Examples · GitLab <https://gitlab.com/djencks/simple-examples> which are each intended to demonstrate one feature without a lot of distracting content :-)
If you like web design, the UI project is going to need some work.
Another very incomplete area is organization of the pages within an Antora component. So far I just concentrated on getting all the content into grammatical asciidoc, without considering organization. If I remember correctly, the existing site has some lists of pages generated from asciidoc header attributes; nearly all the pages are in a flat directory structure. I think it would make sense to look at all the existing documentation and organize it into categories in different Antora modules or topics, and provide lists of pages in the nav that are ordered in a well-thought out arrangement.
If you have any questions, please ask!
Thanks,
David Jencks
> On Jul 15, 2020, at 5:37 PM, Willes Reis <wi...@gmail.com> wrote:
>
> I have seen plenty of discussions and thoughts about evolution in tomee
> site and some hard decisions to make.
> But independently of the goal adopted, I'd really like to help with
> something.
> I like to face challenges and I have been interested in using these tools
> to learn more and contribute to the organization and standardization of the
> platform.
> Is there a small step to get started?
>
> Willes Reis
>
> Em qua., 15 de jul. de 2020 às 12:22, David Jencks <da...@gmail.com>
> escreveu:
>
>>
>>
>>> On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore <
>> jonathan.gallimore@gmail.com> wrote:
>>>
>>>> I recommend we first eliminate the Apache CMS so we have a hands-free
>>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>>> project is the thing that kicks off and runs Antora.
>>>
>>> Sounds good to me.
>>>
>>>> I seriously don't care what we use for them as the majority of the
>> issues
>>> are content, not tool. If we need to rollout a tool to motivate people
>> to
>>> pay attention to the content, let's do it. As long as everything remains
>>> in Asciidoc we are free to switch at any time, so there's no harm in
>> giving
>>> it a try.
>>>
>>> I agree. I recall there's been some discussion about the navigation
>>> hierarchy and splitting stuff into "admin" and "developer", and I don't
>>> think that went anywhere. If we have good content, then the right
>>> structure will follow. Some way of enumerating what we have so we can
>>> identify gaps, and review content feels like a potential starting point.
>>> Seeing what we have on the "old" site that isn't on the "new" site could
>> be
>>> interesting - if I search for something, I usually get a page from the
>>> "old" site.
>>>
>>
>> AFAIK I’ve found all the “old content”, translated it to Asciidoc, and
>> included it in the preview Antora site.
>>
>> David Jencks
>>> Jon
>>>
>>> On Wed, Jul 15, 2020 at 3:35 AM David Blevins <da...@gmail.com>
>>> wrote:
>>>
>>>> Attempting to combine a few threads.
>>>>
>>>> - https://github.com/apache/tomee/pull/670#issuecomment-658452277
>>>>
>>>> Antora-based website progress
>>>> -
>>>>
>> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E
>>>>
>>>> The short version is there was doubt as to if the project was willing to
>>>> consider using Antora. Cesar's feedback is closest to mine:
>>>>
>>>>> - Keep current tomee-site generator as the main content and website
>>>> layout
>>>>> - Once set up as a production-ready instance, keep the Antora setup for
>>>>> the project documentation. This means that the current website link:
>>>>> https://tomee.apache.org/docs.html will be redirected to the Antora
>>>>> awesomeness UI.
>>>>>
>>>>> keep Antora usage for what it was made for, documentation. Keep JBake
>>>> for the static website layout and content.
>>>>
>>>> I would simply amend that to "Keep JBake for the static website layout
>> and
>>>> content [and examples.]"
>>>>
>>>> I'm very in love with the examples and never was too happy when we
>>>> switched to JBake and lost the features I had added to supply javadoc
>>>> links, build instructions and in some cases provide an auto-generated
>> pages
>>>> for them. We're finally getting those features back into the fold and
>>>> there are some other cool things I'd like to do such as adding
>>>> contributor's faces to each example, cross-linking javadoc and examples.
>>>>
>>>> Our main docs, however, are a complete mess.
>>>>
>>>> I seriously don't care what we use for them as the majority of the
>> issues
>>>> are content, not tool. If we need to rollout a tool to motivate people
>> to
>>>> pay attention to the content, let's do it. As long as everything
>> remains
>>>> in Asciidoc we are free to switch at any time, so there's no harm in
>> giving
>>>> it a try.
>>>>
>>>> I think there are two gaps we need to understand to have a better
>>>> conversation about using Antora
>>>>
>>>> - Eliminating the Apache CMS from our lives. This is the biggest
>> blocker
>>>> to any true progress. The only reason our site doesn't automatically
>>>> update now is because we're using the Apache CMS which has a manual
>> publish
>>>> step that takes about an hour of machine time and periodic manual
>>>> checking/poking during that time.
>>>>
>>>> - Understanding `tomee-site-generator` isn't an enemy to Antora and
>>>> doesn't need to die or be eliminated. Among other things, we use it to
>>>> generate asciidoc content when and where we can. It will most likely
>> need
>>>> to run just before Antora. Antora would be building some mix of
>> manually
>>>> created docs and some generated docs. If Antora is not capable of
>>>> committing generated files to git, then `tomee-site-generator` is where
>> we
>>>> would do that work.
>>>>
>>>> I recommend we first eliminate the Apache CMS so we have a hands-free
>>>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>>>> project is the thing that kicks off and runs Antora.
>>>>
>>>>
>>>> Thoughts?
>>>>
>>>>
>>>> --
>>>> David Blevins
>>>> http://twitter.com/dblevins
>>>> http://www.tomitribe.com
>>>>
>>>>
>>
>>
Re: Making Antora actionable
Posted by Willes Reis <wi...@gmail.com>.
I have seen plenty of discussions and thoughts about evolution in tomee
site and some hard decisions to make.
But independently of the goal adopted, I'd really like to help with
something.
I like to face challenges and I have been interested in using these tools
to learn more and contribute to the organization and standardization of the
platform.
Is there a small step to get started?
Willes Reis
Em qua., 15 de jul. de 2020 às 12:22, David Jencks <da...@gmail.com>
escreveu:
>
>
> > On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore <
> jonathan.gallimore@gmail.com> wrote:
> >
> >> I recommend we first eliminate the Apache CMS so we have a hands-free
> > setup. Then I recommend we make it so the `tomee-site-generator` maven
> > project is the thing that kicks off and runs Antora.
> >
> > Sounds good to me.
> >
> >> I seriously don't care what we use for them as the majority of the
> issues
> > are content, not tool. If we need to rollout a tool to motivate people
> to
> > pay attention to the content, let's do it. As long as everything remains
> > in Asciidoc we are free to switch at any time, so there's no harm in
> giving
> > it a try.
> >
> > I agree. I recall there's been some discussion about the navigation
> > hierarchy and splitting stuff into "admin" and "developer", and I don't
> > think that went anywhere. If we have good content, then the right
> > structure will follow. Some way of enumerating what we have so we can
> > identify gaps, and review content feels like a potential starting point.
> > Seeing what we have on the "old" site that isn't on the "new" site could
> be
> > interesting - if I search for something, I usually get a page from the
> > "old" site.
> >
>
> AFAIK I’ve found all the “old content”, translated it to Asciidoc, and
> included it in the preview Antora site.
>
> David Jencks
> > Jon
> >
> > On Wed, Jul 15, 2020 at 3:35 AM David Blevins <da...@gmail.com>
> > wrote:
> >
> >> Attempting to combine a few threads.
> >>
> >> - https://github.com/apache/tomee/pull/670#issuecomment-658452277
> >>
> >> Antora-based website progress
> >> -
> >>
> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E
> >>
> >> The short version is there was doubt as to if the project was willing to
> >> consider using Antora. Cesar's feedback is closest to mine:
> >>
> >>> - Keep current tomee-site generator as the main content and website
> >> layout
> >>> - Once set up as a production-ready instance, keep the Antora setup for
> >>> the project documentation. This means that the current website link:
> >>> https://tomee.apache.org/docs.html will be redirected to the Antora
> >>> awesomeness UI.
> >>>
> >>> keep Antora usage for what it was made for, documentation. Keep JBake
> >> for the static website layout and content.
> >>
> >> I would simply amend that to "Keep JBake for the static website layout
> and
> >> content [and examples.]"
> >>
> >> I'm very in love with the examples and never was too happy when we
> >> switched to JBake and lost the features I had added to supply javadoc
> >> links, build instructions and in some cases provide an auto-generated
> pages
> >> for them. We're finally getting those features back into the fold and
> >> there are some other cool things I'd like to do such as adding
> >> contributor's faces to each example, cross-linking javadoc and examples.
> >>
> >> Our main docs, however, are a complete mess.
> >>
> >> I seriously don't care what we use for them as the majority of the
> issues
> >> are content, not tool. If we need to rollout a tool to motivate people
> to
> >> pay attention to the content, let's do it. As long as everything
> remains
> >> in Asciidoc we are free to switch at any time, so there's no harm in
> giving
> >> it a try.
> >>
> >> I think there are two gaps we need to understand to have a better
> >> conversation about using Antora
> >>
> >> - Eliminating the Apache CMS from our lives. This is the biggest
> blocker
> >> to any true progress. The only reason our site doesn't automatically
> >> update now is because we're using the Apache CMS which has a manual
> publish
> >> step that takes about an hour of machine time and periodic manual
> >> checking/poking during that time.
> >>
> >> - Understanding `tomee-site-generator` isn't an enemy to Antora and
> >> doesn't need to die or be eliminated. Among other things, we use it to
> >> generate asciidoc content when and where we can. It will most likely
> need
> >> to run just before Antora. Antora would be building some mix of
> manually
> >> created docs and some generated docs. If Antora is not capable of
> >> committing generated files to git, then `tomee-site-generator` is where
> we
> >> would do that work.
> >>
> >> I recommend we first eliminate the Apache CMS so we have a hands-free
> >> setup. Then I recommend we make it so the `tomee-site-generator` maven
> >> project is the thing that kicks off and runs Antora.
> >>
> >>
> >> Thoughts?
> >>
> >>
> >> --
> >> David Blevins
> >> http://twitter.com/dblevins
> >> http://www.tomitribe.com
> >>
> >>
>
>
Re: Making Antora actionable
Posted by Willes Reis <wi...@gmail.com>.
No problem... it's your time.
That is great!
I will go synchronize my branches.
Em sáb., 1 de ago. de 2020 às 15:01, David Jencks <da...@gmail.com>
escreveu:
> Sorry for the delay…. I love it!
>
> I merged your PR to master and also rebased the home-page branch on it, I
> hope this doesn’t cause a lot of problems.
>
> The preview is here, including my home-page work:
> https://tomee-preview.s3-us-west-2.amazonaws.com/common/home-page.html <
> https://tomee-preview.s3-us-west-2.amazonaws.com/common/home-page.html>
>
> Thanks!
> David Jencks
>
> > On Jul 27, 2020, at 7:11 PM, Willes Reis <wi...@gmail.com> wrote:
> >
> > Inline...
> >
> > Em seg., 27 de jul. de 2020 às 13:56, David Jencks <
> david.a.jencks@gmail.com>
> > escreveu:
> >
> >> Hi Willes,
> >>
> >> I think the simplest thing to do for now would be for you to have a
> GitHub
> >> fork of my project and push your branch to it, and open a PR. There
> might
> >> be better solutions but I don’t know how to make them work :-)
> >>
> > I did the GitHub fork to me and already created the PR for your project.
> > No problem, let's follow in this way, through GitHub PRs.
> >
> > I think this is a good idea. I think I may have written something
> >> misleading or wrong above about git worktrees; Antora doesn’t recognize
> >> them other than the main checkout. Therefore I think the playbook will
> >> need to have a path to the local checkout of tomEE but list the 3 or 4
> >> branches; the one you happen to be working on currently will have to be
> >> renamed “HEAD”. Alternatively we could expect 3 or 4 complete
> checkouts of
> >> TomEE, but I think that will be too hard to work with.
> >>
> >> I hope I’ve written this in a way you can understand :-)
> >>
> >> David Jencks
> >>
> > Yes, I understood. I tested the "dev-build" with the local-playbook
> > targeting the HEAD branch and works well, i.e. the changes reflect in the
> > build/site folder to preview statically.
> > Of course, before we decide anything, we need to decide where we'll keep
> > our "repository for docs and examples".
> >
> > Willes
>
>
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
Sorry for the delay…. I love it!
I merged your PR to master and also rebased the home-page branch on it, I hope this doesn’t cause a lot of problems.
The preview is here, including my home-page work: https://tomee-preview.s3-us-west-2.amazonaws.com/common/home-page.html <https://tomee-preview.s3-us-west-2.amazonaws.com/common/home-page.html>
Thanks!
David Jencks
> On Jul 27, 2020, at 7:11 PM, Willes Reis <wi...@gmail.com> wrote:
>
> Inline...
>
> Em seg., 27 de jul. de 2020 às 13:56, David Jencks <da...@gmail.com>
> escreveu:
>
>> Hi Willes,
>>
>> I think the simplest thing to do for now would be for you to have a GitHub
>> fork of my project and push your branch to it, and open a PR. There might
>> be better solutions but I don’t know how to make them work :-)
>>
> I did the GitHub fork to me and already created the PR for your project.
> No problem, let's follow in this way, through GitHub PRs.
>
> I think this is a good idea. I think I may have written something
>> misleading or wrong above about git worktrees; Antora doesn’t recognize
>> them other than the main checkout. Therefore I think the playbook will
>> need to have a path to the local checkout of tomEE but list the 3 or 4
>> branches; the one you happen to be working on currently will have to be
>> renamed “HEAD”. Alternatively we could expect 3 or 4 complete checkouts of
>> TomEE, but I think that will be too hard to work with.
>>
>> I hope I’ve written this in a way you can understand :-)
>>
>> David Jencks
>>
> Yes, I understood. I tested the "dev-build" with the local-playbook
> targeting the HEAD branch and works well, i.e. the changes reflect in the
> build/site folder to preview statically.
> Of course, before we decide anything, we need to decide where we'll keep
> our "repository for docs and examples".
>
> Willes
Re: Making Antora actionable
Posted by Willes Reis <wi...@gmail.com>.
Inline...
Em seg., 27 de jul. de 2020 às 13:56, David Jencks <da...@gmail.com>
escreveu:
> Hi Willes,
>
> I think the simplest thing to do for now would be for you to have a GitHub
> fork of my project and push your branch to it, and open a PR. There might
> be better solutions but I don’t know how to make them work :-)
>
I did the GitHub fork to me and already created the PR for your project.
No problem, let's follow in this way, through GitHub PRs.
I think this is a good idea. I think I may have written something
> misleading or wrong above about git worktrees; Antora doesn’t recognize
> them other than the main checkout. Therefore I think the playbook will
> need to have a path to the local checkout of tomEE but list the 3 or 4
> branches; the one you happen to be working on currently will have to be
> renamed “HEAD”. Alternatively we could expect 3 or 4 complete checkouts of
> TomEE, but I think that will be too hard to work with.
>
> I hope I’ve written this in a way you can understand :-)
>
> David Jencks
>
Yes, I understood. I tested the "dev-build" with the local-playbook
targeting the HEAD branch and works well, i.e. the changes reflect in the
build/site folder to preview statically.
Of course, before we decide anything, we need to decide where we'll keep
our "repository for docs and examples".
Willes
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
Hi Willes,
> On Jul 25, 2020, at 1:48 PM, Willes Reis <wi...@gmail.com> wrote:
>
> Hi David Jencks, but anyone can interact ;)
>
> Follow some updates...
>
> I don’t know :-) We could experiment with the header color. it might work
>> to have the same gradient as in the footer in the header. It would be good
>> to get feedback from others on this point.
>>>
>
> I did an experiment with the header successfully. The updates are committed
> locally and I'd like to push it to remote, but it doesn't allow push to
> your repository tomee-antora-ui.
> Thinking about... what do you think about working out a strategy to push
> and branches allowed to accept it?
I think the simplest thing to do for now would be for you to have a GitHub fork of my project and push your branch to it, and open a PR. There might be better solutions but I don’t know how to make them work :-)
>
>
>>> About tomee-antora, I am studying the "todo" item "Make it easy to work
>>> locally" to work in it.
>>
>> As a possible hint, the commented-out urls such as
>>
>> # - url: ./../../tomee-site-generator
>> are what I use for a local playbook. I didn’t know it at the time I did
>> this, but it’s possible to use git work trees to check out all three (or 4
>> now?) main tomee branches at once from one clone.
>>
>> I have all the tomee projects checked out next to one another. This
>> playbook was transplanted from another project so I think all the paths
>> need to be shortened by one parent directory, e.g.
>> ./../tomee-site-generator.
>>
> About this, I read about the "Author Mode" in Antora and was wondering
> whether this would be tangible for our purpose.
> I am updating the tomee-antora playbook for some tests and will inform you
> if it is ok.
> Right now, I copied the antora-playbook.yml to local-antora-playbook.yml
> changing the content > sources > url to local resources, considering that
> all cloned git repositories are in the same level as this project. Even
> more, I am making an appropriate npm script as "dev-clean-build" to
> automate build as you made.
I think this is a good idea. I think I may have written something misleading or wrong above about git worktrees; Antora doesn’t recognize them other than the main checkout. Therefore I think the playbook will need to have a path to the local checkout of tomEE but list the 3 or 4 branches; the one you happen to be working on currently will have to be renamed “HEAD”. Alternatively we could expect 3 or 4 complete checkouts of TomEE, but I think that will be too hard to work with.
I hope I’ve written this in a way you can understand :-)
David Jencks
>
> Willes.
Re: Making Antora actionable
Posted by Willes Reis <wi...@gmail.com>.
Hi David Jencks, but anyone can interact ;)
Follow some updates...
I don’t know :-) We could experiment with the header color. it might work
> to have the same gradient as in the footer in the header. It would be good
> to get feedback from others on this point.
> >
I did an experiment with the header successfully. The updates are committed
locally and I'd like to push it to remote, but it doesn't allow push to
your repository tomee-antora-ui.
Thinking about... what do you think about working out a strategy to push
and branches allowed to accept it?
> > About tomee-antora, I am studying the "todo" item "Make it easy to work
> > locally" to work in it.
>
> As a possible hint, the commented-out urls such as
>
> # - url: ./../../tomee-site-generator
> are what I use for a local playbook. I didn’t know it at the time I did
> this, but it’s possible to use git work trees to check out all three (or 4
> now?) main tomee branches at once from one clone.
>
> I have all the tomee projects checked out next to one another. This
> playbook was transplanted from another project so I think all the paths
> need to be shortened by one parent directory, e.g.
> ./../tomee-site-generator.
>
About this, I read about the "Author Mode" in Antora and was wondering
whether this would be tangible for our purpose.
I am updating the tomee-antora playbook for some tests and will inform you
if it is ok.
Right now, I copied the antora-playbook.yml to local-antora-playbook.yml
changing the content > sources > url to local resources, considering that
all cloned git repositories are in the same level as this project. Even
more, I am making an appropriate npm script as "dev-clean-build" to
automate build as you made.
Willes.
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
inline...
> On Jul 17, 2020, at 2:53 PM, Willes Reis <wi...@gmail.com> wrote:
>
> inline and other points...
>
>
>> I added a TOC and the {done} checkmark seems to display nicely in that. I
>> like having things organized in sections as it’s easier to write text
>> describing the activity, and now the TOC provides a list view. What do you
>> think?
>>
>> Thanks,
>> David Jencks
>>>
>
> The TOC is great, I agree that it's good to organize. About {done}
> checkmark, I didn't know, +1 learned. Thanks!
>
> About tomee-antora-ui, it looks like most of it has already been done, but
> the items in "todo" refer to decisions.
> How to approach this subject?
I don’t know :-) We could experiment with the header color. it might work to have the same gradient as in the footer in the header. It would be good to get feedback from others on this point.
>
> About tomee-antora, I am studying the "todo" item "Make it easy to work
> locally" to work in it.
As a possible hint, the commented-out urls such as
# - url: ./../../tomee-site-generator
are what I use for a local playbook. I didn’t know it at the time I did this, but it’s possible to use git work trees to check out all three (or 4 now?) main tomee branches at once from one clone.
I have all the tomee projects checked out next to one another. This playbook was transplanted from another project so I think all the paths need to be shortened by one parent directory, e.g. ./../tomee-site-generator.
David
>
> Willes
Re: Making Antora actionable
Posted by Willes Reis <wi...@gmail.com>.
inline and other points...
> I added a TOC and the {done} checkmark seems to display nicely in that. I
> like having things organized in sections as it’s easier to write text
> describing the activity, and now the TOC provides a list view. What do you
> think?
>
> Thanks,
> David Jencks
> >
The TOC is great, I agree that it's good to organize. About {done}
checkmark, I didn't know, +1 learned. Thanks!
About tomee-antora-ui, it looks like most of it has already been done, but
the items in "todo" refer to decisions.
How to approach this subject?
About tomee-antora, I am studying the "todo" item "Make it easy to work
locally" to work in it.
Willes
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
Inline...
> On Jul 16, 2020, at 11:39 PM, Willes Reis <wi...@gmail.com> wrote:
>
> Hi David Jencks, thank you for updates.
>
> Em qui., 16 de jul. de 2020 às 18:13, David Jencks <da...@gmail.com>
> escreveu:
>
>> Hi Willes,
>>
>> I’ve never seen that particular error from npm! I changed the relevant
>> url to be https://, could you try again?
>
>
> I tried the build again and was successful: downloaded node modules,
> processed antora-playbook and built site folder.
> Browsing on this local site was great!
>
Wonderful!
>
>>
>>
> I also added some todo.adoc files to these two new projects…. take a look,
>> are they more or less what you had in mind?
>>
>
> Yes, it's more or less that I had in mind.
> I thought about keeping it in checklist, as in asciidoc:
> * [x] Task that is already done
> * [ ] Task that is missing
> ... to make it visible to anyone who checks the repository, understanding
> the progress, what already was done and what is missing, as simple as
> possible.
> With this in mind and your wide knowledge, I will know the first steps to
> help you even more.
I added a TOC and the {done} checkmark seems to display nicely in that. I like having things organized in sections as it’s easier to write text describing the activity, and now the TOC provides a list view. What do you think?
Thanks,
David Jencks
>
> Willes
Re: Making Antora actionable
Posted by Willes Reis <wi...@gmail.com>.
Hi David Jencks, thank you for updates.
Em qui., 16 de jul. de 2020 às 18:13, David Jencks <da...@gmail.com>
escreveu:
> Hi Willes,
>
> I’ve never seen that particular error from npm! I changed the relevant
> url to be https://, could you try again?
I tried the build again and was successful: downloaded node modules,
processed antora-playbook and built site folder.
Browsing on this local site was great!
>
>
I also added some todo.adoc files to these two new projects…. take a look,
> are they more or less what you had in mind?
>
Yes, it's more or less that I had in mind.
I thought about keeping it in checklist, as in asciidoc:
* [x] Task that is already done
* [ ] Task that is missing
... to make it visible to anyone who checks the repository, understanding
the progress, what already was done and what is missing, as simple as
possible.
With this in mind and your wide knowledge, I will know the first steps to
help you even more.
Willes
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
Hi Willes,
I’ve never seen that particular error from npm! I changed the relevant url to be https://, could you try again?
I also added some todo.adoc files to these two new projects…. take a look, are they more or less what you had in mind?
Thanks!
David Jencks
> On Jul 16, 2020, at 1:00 PM, Willes Reis <wi...@gmail.com> wrote:
>
> Hi David, thanks for your effort.
>
>
>>> On Jul 15, 2020, at 6:03 PM, David Jencks <da...@gmail.com>
>> wrote:
>>>
>>> I’ve:
>>>
>>> - started an Antora UI bundle project for TomEE: tomee-antora-ui <
>> https://github.com/djencks/tomee-antora-ui>
>>> It’s already built, but if you want to build it yourself, clone it, run
>> npm i, and gulp.
>
> I did fork/clone this project, but I haven't built it yet..
>
>
>>> In order to track what is changed from the default UI, I used my
>> slightly experimental UI builder. If we want to proceed on this path I
>> can release it to npm; right now it’s in my space on AWS.
>>
>>
>>> I set header/footer colors/images to match the existing site and removed
>> the cruft from the header. I didn’t try to match header/footer content
>> with the existing site since I think it needs to be rethought for Antora.
>>
> I could help you with this details in design/UI asap.
>
>> - started an Antora playbook project for TomEE: tomee-antora <
>> https://github.com/djencks/tomee-antora>
>>> To build this, clone it, and run npm run clean-build. The site will be
>> at build/site.
>>> I have not yet provided a maven project to run this.
>>
>
> I did fork/clone this project and run build, but there was some error at
> authentication in your GitHub repo tomee-antora-ui, as follows:
> Perhaps you can understand and know what to do.
>
>
>> willesreis@host tomme-antora % npm run clean-build
>>
>
>>> @ clean-build /Users/willesreis/tomee-antora
>>
>>> npm run clean-install;npm run build
>>
>>
>>
>>> @ clean-install /Users/willesreis/tomee-antora
>>
>>> rm -rf node_modules/ .cache/ package-lock.json;npm i --cache=.cache/npm
>>
>>
>> The authenticity of host 'github.com (18.228.52.138)' can't be
>> established.tf8@0.0.1 fetched in 1083ms
>>
>> RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
>>
>> ⸨ ░░░░░░░░░░░░░░⸩ ⠼ fetchMetadata: sill pacote version manifest for
>> to-utf8@0.0.1 fetched in 1083ms
>>
>> npm ERR! Error while executing:
>>
>> npm ERR! /usr/bin/git ls-remote -h -t ssh://
>> git@github.com/djencks/tomee-antora-ui.git
>>
>> npm ERR!
>>
>> npm ERR! Host key verification failed.
>>
>> npm ERR! fatal: Could not read from remote repository.
>>
>> npm ERR!
>>
>> npm ERR! Please make sure you have the correct access rights
>>
>> npm ERR! and the repository exists.
>>
>> npm ERR!
>>
>> npm ERR! exited with error code: 128
>>
>
> I suggest that we put a ".adoc" file kind "to do" or "progress" on each
> repo, on which we can write all of things to do, i.e. our path, and we go
> "checking" each item as we progress. What do you think?
>
> Willes Reis
Re: Making Antora actionable
Posted by Willes Reis <wi...@gmail.com>.
Hi David, thanks for your effort.
> > On Jul 15, 2020, at 6:03 PM, David Jencks <da...@gmail.com>
> wrote:
> >
> > I’ve:
> >
> > - started an Antora UI bundle project for TomEE: tomee-antora-ui <
> https://github.com/djencks/tomee-antora-ui>
> > It’s already built, but if you want to build it yourself, clone it, run
> npm i, and gulp.
I did fork/clone this project, but I haven't built it yet..
> > In order to track what is changed from the default UI, I used my
> slightly experimental UI builder. If we want to proceed on this path I
> can release it to npm; right now it’s in my space on AWS.
>
>
> > I set header/footer colors/images to match the existing site and removed
> the cruft from the header. I didn’t try to match header/footer content
> with the existing site since I think it needs to be rethought for Antora.
>
I could help you with this details in design/UI asap.
> - started an Antora playbook project for TomEE: tomee-antora <
> https://github.com/djencks/tomee-antora>
> > To build this, clone it, and run npm run clean-build. The site will be
> at build/site.
> > I have not yet provided a maven project to run this.
>
I did fork/clone this project and run build, but there was some error at
authentication in your GitHub repo tomee-antora-ui, as follows:
Perhaps you can understand and know what to do.
> willesreis@host tomme-antora % npm run clean-build
>
> > @ clean-build /Users/willesreis/tomee-antora
>
> > npm run clean-install;npm run build
>
>
>
> > @ clean-install /Users/willesreis/tomee-antora
>
> > rm -rf node_modules/ .cache/ package-lock.json;npm i --cache=.cache/npm
>
>
> The authenticity of host 'github.com (18.228.52.138)' can't be
> established.tf8@0.0.1 fetched in 1083ms
>
> RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
>
> ⸨ ░░░░░░░░░░░░░░⸩ ⠼ fetchMetadata: sill pacote version manifest for
> to-utf8@0.0.1 fetched in 1083ms
>
> npm ERR! Error while executing:
>
> npm ERR! /usr/bin/git ls-remote -h -t ssh://
> git@github.com/djencks/tomee-antora-ui.git
>
> npm ERR!
>
> npm ERR! Host key verification failed.
>
> npm ERR! fatal: Could not read from remote repository.
>
> npm ERR!
>
> npm ERR! Please make sure you have the correct access rights
>
> npm ERR! and the repository exists.
>
> npm ERR!
>
> npm ERR! exited with error code: 128
>
I suggest that we put a ".adoc" file kind "to do" or "progress" on each
repo, on which we can write all of things to do, i.e. our path, and we go
"checking" each item as we progress. What do you think?
Willes Reis
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
I’ve updated the UI to more closely match the existing site (especially the header :-) and enabled prev/next pagination, and updated the preview.
IMO this is close to usable.
We still have to decide on what should go in the footer, but that may be more evident when the navigation is developed to a workable state.
David Jencks
> On Jul 15, 2020, at 6:03 PM, David Jencks <da...@gmail.com> wrote:
>
> I’ve:
>
> - started an Antora UI bundle project for TomEE: tomee-antora-ui <https://github.com/djencks/tomee-antora-ui>
> It’s already built, but if you want to build it yourself, clone it, run npm i, and gulp.
> In order to track what is changed from the default UI, I used my slightly experimental UI builder. If we want to proceed on this path I can release it to npm; right now it’s in my space on AWS.
>
> I set header/footer colors/images to match the existing site and removed the cruft from the header. I didn’t try to match header/footer content with the existing site since I think it needs to be rethought for Antora.
>
> - started an Antora playbook project for TomEE: tomee-antora <https://github.com/djencks/tomee-antora>
> To build this, clone it, and run npm run clean-build. The site will be at build/site.
> I have not yet provided a maven project to run this.
>
> I removed the examples from what was previously in the Antora site.
>
> The results are visible at https://tomee-preview.s3-us-west-2.amazonaws.com/common/contribute.html <https://tomee-preview.s3-us-west-2.amazonaws.com/common/contribute.html> (a somewhat arbitrary start page). Since an AWS bucket isn’t a web server or a local file system, there are some strange things happening for some links.
>
> Comments:
>
> - In order to combine the playbook project with tomee-site-generator, I think tomee-site-generator needs to become a multi-module reactor maven project. Let’s make sure that is actually the most sensible approach before proceeding.
>
> - I believe this preview includes all of what I think people have been describing as the non-example non-doc content. I think this includes all the stuff previously buried in secret in, mostly, markdown and html in the CMS. IIUC there’s some objection to this being in the Antora part of the site. I would like a clear explanation of what is better for this to be non-Antora content.
>
> - IIRC the content for 7.0, 7.1, and 8 is identical (there might be slight differences, of a couple of pages). I’d suggest that since there is not enough interest to maintain the site at a high level, this be collapsed to one version. Small differences can be pointed out with “since 8.0” etc. If in the future new docs for 9.0 are actually written, that would be a good time to add another version.
>
> - I haven’t yet considered how this might be combined with non-Antora parts of the site. I pointed out a few messages ago that at least the Antora part can easily use ASF infrastructure to publish to the appropriate git repo.
>
> - I haven’t made any attempt to set up reasonable navigation in the site. I think all pages are present in navigation, but wouldn’t promise anything. I think this may relate to the “what needs to be generated” discussion.
>
> I think it would be really great if this could get enough attention so that we can end up with a new site soon.
>
> Thanks!
> David Jencks
>
>> On Jul 15, 2020, at 8:22 AM, David Jencks <david.a.jencks@gmail.com <ma...@gmail.com>> wrote:
>>
>>
>>
>>> On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore <jonathan.gallimore@gmail.com <ma...@gmail.com>> wrote:
>>>
>>>> I recommend we first eliminate the Apache CMS so we have a hands-free
>>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>>> project is the thing that kicks off and runs Antora.
>>>
>>> Sounds good to me.
>>>
>>>> I seriously don't care what we use for them as the majority of the issues
>>> are content, not tool. If we need to rollout a tool to motivate people to
>>> pay attention to the content, let's do it. As long as everything remains
>>> in Asciidoc we are free to switch at any time, so there's no harm in giving
>>> it a try.
>>>
>>> I agree. I recall there's been some discussion about the navigation
>>> hierarchy and splitting stuff into "admin" and "developer", and I don't
>>> think that went anywhere. If we have good content, then the right
>>> structure will follow. Some way of enumerating what we have so we can
>>> identify gaps, and review content feels like a potential starting point.
>>> Seeing what we have on the "old" site that isn't on the "new" site could be
>>> interesting - if I search for something, I usually get a page from the
>>> "old" site.
>>>
>>
>> AFAIK I’ve found all the “old content”, translated it to Asciidoc, and included it in the preview Antora site.
>>
>> David Jencks
>>> Jon
>>>
>>> On Wed, Jul 15, 2020 at 3:35 AM David Blevins <david.blevins@gmail.com <ma...@gmail.com>>
>>> wrote:
>>>
>>>> Attempting to combine a few threads.
>>>>
>>>> - https://github.com/apache/tomee/pull/670#issuecomment-658452277 <https://github.com/apache/tomee/pull/670#issuecomment-658452277>
>>>>
>>>> Antora-based website progress
>>>> -
>>>> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E <https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E>
>>>>
>>>> The short version is there was doubt as to if the project was willing to
>>>> consider using Antora. Cesar's feedback is closest to mine:
>>>>
>>>>> - Keep current tomee-site generator as the main content and website
>>>> layout
>>>>> - Once set up as a production-ready instance, keep the Antora setup for
>>>>> the project documentation. This means that the current website link:
>>>>> https://tomee.apache.org/docs.html will be redirected to the Antora
>>>>> awesomeness UI.
>>>>>
>>>>> keep Antora usage for what it was made for, documentation. Keep JBake
>>>> for the static website layout and content.
>>>>
>>>> I would simply amend that to "Keep JBake for the static website layout and
>>>> content [and examples.]"
>>>>
>>>> I'm very in love with the examples and never was too happy when we
>>>> switched to JBake and lost the features I had added to supply javadoc
>>>> links, build instructions and in some cases provide an auto-generated pages
>>>> for them. We're finally getting those features back into the fold and
>>>> there are some other cool things I'd like to do such as adding
>>>> contributor's faces to each example, cross-linking javadoc and examples.
>>>>
>>>> Our main docs, however, are a complete mess.
>>>>
>>>> I seriously don't care what we use for them as the majority of the issues
>>>> are content, not tool. If we need to rollout a tool to motivate people to
>>>> pay attention to the content, let's do it. As long as everything remains
>>>> in Asciidoc we are free to switch at any time, so there's no harm in giving
>>>> it a try.
>>>>
>>>> I think there are two gaps we need to understand to have a better
>>>> conversation about using Antora
>>>>
>>>> - Eliminating the Apache CMS from our lives. This is the biggest blocker
>>>> to any true progress. The only reason our site doesn't automatically
>>>> update now is because we're using the Apache CMS which has a manual publish
>>>> step that takes about an hour of machine time and periodic manual
>>>> checking/poking during that time.
>>>>
>>>> - Understanding `tomee-site-generator` isn't an enemy to Antora and
>>>> doesn't need to die or be eliminated. Among other things, we use it to
>>>> generate asciidoc content when and where we can. It will most likely need
>>>> to run just before Antora. Antora would be building some mix of manually
>>>> created docs and some generated docs. If Antora is not capable of
>>>> committing generated files to git, then `tomee-site-generator` is where we
>>>> would do that work.
>>>>
>>>> I recommend we first eliminate the Apache CMS so we have a hands-free
>>>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>>>> project is the thing that kicks off and runs Antora.
>>>>
>>>>
>>>> Thoughts?
>>>>
>>>>
>>>> --
>>>> David Blevins
>>>> http://twitter.com/dblevins
>>>> http://www.tomitribe.com
>
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
I’ve:
- started an Antora UI bundle project for TomEE: tomee-antora-ui <https://github.com/djencks/tomee-antora-ui>
It’s already built, but if you want to build it yourself, clone it, run npm i, and gulp.
In order to track what is changed from the default UI, I used my slightly experimental UI builder. If we want to proceed on this path I can release it to npm; right now it’s in my space on AWS.
I set header/footer colors/images to match the existing site and removed the cruft from the header. I didn’t try to match header/footer content with the existing site since I think it needs to be rethought for Antora.
- started an Antora playbook project for TomEE: tomee-antora <https://github.com/djencks/tomee-antora>
To build this, clone it, and run npm run clean-build. The site will be at build/site.
I have not yet provided a maven project to run this.
I removed the examples from what was previously in the Antora site.
The results are visible at https://tomee-preview.s3-us-west-2.amazonaws.com/common/contribute.html <https://tomee-preview.s3-us-west-2.amazonaws.com/common/contribute.html> (a somewhat arbitrary start page). Since an AWS bucket isn’t a web server or a local file system, there are some strange things happening for some links.
Comments:
- In order to combine the playbook project with tomee-site-generator, I think tomee-site-generator needs to become a multi-module reactor maven project. Let’s make sure that is actually the most sensible approach before proceeding.
- I believe this preview includes all of what I think people have been describing as the non-example non-doc content. I think this includes all the stuff previously buried in secret in, mostly, markdown and html in the CMS. IIUC there’s some objection to this being in the Antora part of the site. I would like a clear explanation of what is better for this to be non-Antora content.
- IIRC the content for 7.0, 7.1, and 8 is identical (there might be slight differences, of a couple of pages). I’d suggest that since there is not enough interest to maintain the site at a high level, this be collapsed to one version. Small differences can be pointed out with “since 8.0” etc. If in the future new docs for 9.0 are actually written, that would be a good time to add another version.
- I haven’t yet considered how this might be combined with non-Antora parts of the site. I pointed out a few messages ago that at least the Antora part can easily use ASF infrastructure to publish to the appropriate git repo.
- I haven’t made any attempt to set up reasonable navigation in the site. I think all pages are present in navigation, but wouldn’t promise anything. I think this may relate to the “what needs to be generated” discussion.
I think it would be really great if this could get enough attention so that we can end up with a new site soon.
Thanks!
David Jencks
> On Jul 15, 2020, at 8:22 AM, David Jencks <da...@gmail.com> wrote:
>
>
>
>> On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore <jo...@gmail.com> wrote:
>>
>>> I recommend we first eliminate the Apache CMS so we have a hands-free
>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>> project is the thing that kicks off and runs Antora.
>>
>> Sounds good to me.
>>
>>> I seriously don't care what we use for them as the majority of the issues
>> are content, not tool. If we need to rollout a tool to motivate people to
>> pay attention to the content, let's do it. As long as everything remains
>> in Asciidoc we are free to switch at any time, so there's no harm in giving
>> it a try.
>>
>> I agree. I recall there's been some discussion about the navigation
>> hierarchy and splitting stuff into "admin" and "developer", and I don't
>> think that went anywhere. If we have good content, then the right
>> structure will follow. Some way of enumerating what we have so we can
>> identify gaps, and review content feels like a potential starting point.
>> Seeing what we have on the "old" site that isn't on the "new" site could be
>> interesting - if I search for something, I usually get a page from the
>> "old" site.
>>
>
> AFAIK I’ve found all the “old content”, translated it to Asciidoc, and included it in the preview Antora site.
>
> David Jencks
>> Jon
>>
>> On Wed, Jul 15, 2020 at 3:35 AM David Blevins <da...@gmail.com>
>> wrote:
>>
>>> Attempting to combine a few threads.
>>>
>>> - https://github.com/apache/tomee/pull/670#issuecomment-658452277
>>>
>>> Antora-based website progress
>>> -
>>> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E
>>>
>>> The short version is there was doubt as to if the project was willing to
>>> consider using Antora. Cesar's feedback is closest to mine:
>>>
>>>> - Keep current tomee-site generator as the main content and website
>>> layout
>>>> - Once set up as a production-ready instance, keep the Antora setup for
>>>> the project documentation. This means that the current website link:
>>>> https://tomee.apache.org/docs.html will be redirected to the Antora
>>>> awesomeness UI.
>>>>
>>>> keep Antora usage for what it was made for, documentation. Keep JBake
>>> for the static website layout and content.
>>>
>>> I would simply amend that to "Keep JBake for the static website layout and
>>> content [and examples.]"
>>>
>>> I'm very in love with the examples and never was too happy when we
>>> switched to JBake and lost the features I had added to supply javadoc
>>> links, build instructions and in some cases provide an auto-generated pages
>>> for them. We're finally getting those features back into the fold and
>>> there are some other cool things I'd like to do such as adding
>>> contributor's faces to each example, cross-linking javadoc and examples.
>>>
>>> Our main docs, however, are a complete mess.
>>>
>>> I seriously don't care what we use for them as the majority of the issues
>>> are content, not tool. If we need to rollout a tool to motivate people to
>>> pay attention to the content, let's do it. As long as everything remains
>>> in Asciidoc we are free to switch at any time, so there's no harm in giving
>>> it a try.
>>>
>>> I think there are two gaps we need to understand to have a better
>>> conversation about using Antora
>>>
>>> - Eliminating the Apache CMS from our lives. This is the biggest blocker
>>> to any true progress. The only reason our site doesn't automatically
>>> update now is because we're using the Apache CMS which has a manual publish
>>> step that takes about an hour of machine time and periodic manual
>>> checking/poking during that time.
>>>
>>> - Understanding `tomee-site-generator` isn't an enemy to Antora and
>>> doesn't need to die or be eliminated. Among other things, we use it to
>>> generate asciidoc content when and where we can. It will most likely need
>>> to run just before Antora. Antora would be building some mix of manually
>>> created docs and some generated docs. If Antora is not capable of
>>> committing generated files to git, then `tomee-site-generator` is where we
>>> would do that work.
>>>
>>> I recommend we first eliminate the Apache CMS so we have a hands-free
>>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>>> project is the thing that kicks off and runs Antora.
>>>
>>>
>>> Thoughts?
>>>
>>>
>>> --
>>> David Blevins
>>> http://twitter.com/dblevins
>>> http://www.tomitribe.com
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
> On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore <jo...@gmail.com> wrote:
>
>> I recommend we first eliminate the Apache CMS so we have a hands-free
> setup. Then I recommend we make it so the `tomee-site-generator` maven
> project is the thing that kicks off and runs Antora.
>
> Sounds good to me.
>
>> I seriously don't care what we use for them as the majority of the issues
> are content, not tool. If we need to rollout a tool to motivate people to
> pay attention to the content, let's do it. As long as everything remains
> in Asciidoc we are free to switch at any time, so there's no harm in giving
> it a try.
>
> I agree. I recall there's been some discussion about the navigation
> hierarchy and splitting stuff into "admin" and "developer", and I don't
> think that went anywhere. If we have good content, then the right
> structure will follow. Some way of enumerating what we have so we can
> identify gaps, and review content feels like a potential starting point.
> Seeing what we have on the "old" site that isn't on the "new" site could be
> interesting - if I search for something, I usually get a page from the
> "old" site.
>
AFAIK I’ve found all the “old content”, translated it to Asciidoc, and included it in the preview Antora site.
David Jencks
> Jon
>
> On Wed, Jul 15, 2020 at 3:35 AM David Blevins <da...@gmail.com>
> wrote:
>
>> Attempting to combine a few threads.
>>
>> - https://github.com/apache/tomee/pull/670#issuecomment-658452277
>>
>> Antora-based website progress
>> -
>> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E
>>
>> The short version is there was doubt as to if the project was willing to
>> consider using Antora. Cesar's feedback is closest to mine:
>>
>>> - Keep current tomee-site generator as the main content and website
>> layout
>>> - Once set up as a production-ready instance, keep the Antora setup for
>>> the project documentation. This means that the current website link:
>>> https://tomee.apache.org/docs.html will be redirected to the Antora
>>> awesomeness UI.
>>>
>>> keep Antora usage for what it was made for, documentation. Keep JBake
>> for the static website layout and content.
>>
>> I would simply amend that to "Keep JBake for the static website layout and
>> content [and examples.]"
>>
>> I'm very in love with the examples and never was too happy when we
>> switched to JBake and lost the features I had added to supply javadoc
>> links, build instructions and in some cases provide an auto-generated pages
>> for them. We're finally getting those features back into the fold and
>> there are some other cool things I'd like to do such as adding
>> contributor's faces to each example, cross-linking javadoc and examples.
>>
>> Our main docs, however, are a complete mess.
>>
>> I seriously don't care what we use for them as the majority of the issues
>> are content, not tool. If we need to rollout a tool to motivate people to
>> pay attention to the content, let's do it. As long as everything remains
>> in Asciidoc we are free to switch at any time, so there's no harm in giving
>> it a try.
>>
>> I think there are two gaps we need to understand to have a better
>> conversation about using Antora
>>
>> - Eliminating the Apache CMS from our lives. This is the biggest blocker
>> to any true progress. The only reason our site doesn't automatically
>> update now is because we're using the Apache CMS which has a manual publish
>> step that takes about an hour of machine time and periodic manual
>> checking/poking during that time.
>>
>> - Understanding `tomee-site-generator` isn't an enemy to Antora and
>> doesn't need to die or be eliminated. Among other things, we use it to
>> generate asciidoc content when and where we can. It will most likely need
>> to run just before Antora. Antora would be building some mix of manually
>> created docs and some generated docs. If Antora is not capable of
>> committing generated files to git, then `tomee-site-generator` is where we
>> would do that work.
>>
>> I recommend we first eliminate the Apache CMS so we have a hands-free
>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>> project is the thing that kicks off and runs Antora.
>>
>>
>> Thoughts?
>>
>>
>> --
>> David Blevins
>> http://twitter.com/dblevins
>> http://www.tomitribe.com
>>
>>
Re: Making Antora actionable
Posted by Jonathan Gallimore <jo...@gmail.com>.
> I recommend we first eliminate the Apache CMS so we have a hands-free
setup. Then I recommend we make it so the `tomee-site-generator` maven
project is the thing that kicks off and runs Antora.
Sounds good to me.
> I seriously don't care what we use for them as the majority of the issues
are content, not tool. If we need to rollout a tool to motivate people to
pay attention to the content, let's do it. As long as everything remains
in Asciidoc we are free to switch at any time, so there's no harm in giving
it a try.
I agree. I recall there's been some discussion about the navigation
hierarchy and splitting stuff into "admin" and "developer", and I don't
think that went anywhere. If we have good content, then the right
structure will follow. Some way of enumerating what we have so we can
identify gaps, and review content feels like a potential starting point.
Seeing what we have on the "old" site that isn't on the "new" site could be
interesting - if I search for something, I usually get a page from the
"old" site.
Jon
On Wed, Jul 15, 2020 at 3:35 AM David Blevins <da...@gmail.com>
wrote:
> Attempting to combine a few threads.
>
> - https://github.com/apache/tomee/pull/670#issuecomment-658452277
>
> Antora-based website progress
> -
> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E
>
> The short version is there was doubt as to if the project was willing to
> consider using Antora. Cesar's feedback is closest to mine:
>
> > - Keep current tomee-site generator as the main content and website
> layout
> > - Once set up as a production-ready instance, keep the Antora setup for
> > the project documentation. This means that the current website link:
> > https://tomee.apache.org/docs.html will be redirected to the Antora
> > awesomeness UI.
> >
> > keep Antora usage for what it was made for, documentation. Keep JBake
> for the static website layout and content.
>
> I would simply amend that to "Keep JBake for the static website layout and
> content [and examples.]"
>
> I'm very in love with the examples and never was too happy when we
> switched to JBake and lost the features I had added to supply javadoc
> links, build instructions and in some cases provide an auto-generated pages
> for them. We're finally getting those features back into the fold and
> there are some other cool things I'd like to do such as adding
> contributor's faces to each example, cross-linking javadoc and examples.
>
> Our main docs, however, are a complete mess.
>
> I seriously don't care what we use for them as the majority of the issues
> are content, not tool. If we need to rollout a tool to motivate people to
> pay attention to the content, let's do it. As long as everything remains
> in Asciidoc we are free to switch at any time, so there's no harm in giving
> it a try.
>
> I think there are two gaps we need to understand to have a better
> conversation about using Antora
>
> - Eliminating the Apache CMS from our lives. This is the biggest blocker
> to any true progress. The only reason our site doesn't automatically
> update now is because we're using the Apache CMS which has a manual publish
> step that takes about an hour of machine time and periodic manual
> checking/poking during that time.
>
> - Understanding `tomee-site-generator` isn't an enemy to Antora and
> doesn't need to die or be eliminated. Among other things, we use it to
> generate asciidoc content when and where we can. It will most likely need
> to run just before Antora. Antora would be building some mix of manually
> created docs and some generated docs. If Antora is not capable of
> committing generated files to git, then `tomee-site-generator` is where we
> would do that work.
>
> I recommend we first eliminate the Apache CMS so we have a hands-free
> setup. Then I recommend we make it so the `tomee-site-generator` maven
> project is the thing that kicks off and runs Antora.
>
>
> Thoughts?
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
>
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
I’m also helping Aries move off CMS to an Antora site, and I may postpone working on the TomEE site more until that is more complete and I know more what to expect.
Two things we can expect here are
- a PMC vote to adopt Antora/git site publishing for parts of the site from CMS
- an infra ticket to set ??? up.
David Jencks
> On Aug 11, 2020, at 8:52 AM, David Jencks <da...@gmail.com> wrote:
>
> David Blevins and I had a long chat about the history of OpenEJB/TomEE documentation and I have a considerably different perspective now on the best way forward. I’d say the most fundamental shift is my realizing that even if doing everything with Antora is the most elegant and efficient solution, it may not be appropriate for TomEE because it involves extending the doc build system with javascript, whereas TomEE developers are more likely to be comfortable with java. Learning a new language in order to improve or even understand the doc build is too big a barrier. I’m likely to continue to see how, for instance, “marketing pages” and the tricks in the examples can be implemented in Antora, but because I want to learn how to do those things rather than because they are appropriate to use in TomEE.
>
> I think the following steps make sense:
>
> - versioned doc consolidation: There are now 5 copies of the “tomee” versioned docs; one in common, and 4 identical copies done by asciidoc includes. Looking at one of these includes, it’s not very obvious how to edit the page, and certainly having one copy in ‘common’ is silly. So, the “originals” should be moved to one of the versions. The obvious choices are 7.0.x and 8.0.x. 7 might make it more obvious that changing the doc will change all 4 versions, but development is most convenient on master, 8.0. To make it easiest to locate the actual source, I’ll move the ‘original’ to 8.0. I hope that there will be a period of organization and improvement of the existing content followed by writing new content. After reorganization has settled down it may make sense to replace the “include” copies with one or two actual copies in the 7.0.x and 7.1.x branches so changes in master won’t inadvertently affect older versions.
>
> - common doc consolidation. The pages that show up in the common component come from two repos: tomee-site-generator and tomee-site. I don’t think it’s a good idea to have content in the same repo as site generator code, so I’m planning to move the content in tomee-site-generator to tomee-site. David said something indicating that this may not be an appropriate location, so perhaps a new repo would be appropriate…. I’ll investigate. Also, this content includes all the stuff that was previously in CMS and not served by the current site build. It’s apt to need a lot of editing, consolidation, etc, and it’s possible that this entire component should not be produced by Antora. However, at the moment, the only place all the content is accessible for consideration is in the Antora build, so I propose we leave it there for now, organize it, and consider what to do with it afterwards. One possibility, since Antora deals well with multiple versions, is to have something similar to the current common content minus the doc pages mentioned above as a “historical content” component version with the “current common” component version redirect to elsewhere.
>
> - examples. I’ve accumulated a pile of asciidoc fixes for the READMEs and I’ll see about getting them back to the master branch.
>
> - source directory structure. David pointed out that the shorter the path to the actual adoc files the more likely people are to find them…. I’ll see how much the path can be shortened.
>
> - publishing. It’s very tempting to work hard to create a highly unified site where the Antora and non-antora pieces are indistinguishable, however that may not be the best plan here. One of the persistent problems with documentation is that no one likes to work on it. Any complexity or difficulty is likely to deter people from contributing. A unified site would need a way for all the pieces of the site build to not step on each other, which could be hard to maintain. It may well be simpler to have two sites, one containing the front page, “marketing material”, possibly eventually the “common” component, the examples, and the other the Antora generated docs. This requires more investigation but the two-site approach is very attractive as reducing “friction”.
>
>
> Possibly this can lead quickly to actually getting the Antora portion of the site published soon.
>
> Thanks,
> David Jencks
>
>
>> On Aug 10, 2020, at 1:44 PM, David Jencks <david.a.jencks@gmail.com <ma...@gmail.com>> wrote:
>>
>> The reason Antora has a separate front page is that Dan didn’t write asciidoctor-openblock <https://gitlab.com/djencks/asciidoctor-openblock>. Since I did, it’s easy to have a front page generated by Antora. He’s known about this possibility for at least 5 years, but never found the time or motivation to do it.
>>
>> If you have specific complaints about the front page I wrote, please air them rather than ignoring my request for feedback.
>>
>> Could you be extremely specific about what you want generated by Antora and what by tomee-site-generator and what by some other unnamed tool? Are there parts of the current antora preview site that you think should not be generated by Antora? (I expect to add examples to the preview shortly, but we can discuss that separately).
>>
>> thanks
>> David Jencks
>>
>>> On Aug 10, 2020, at 1:09 PM, David Blevins <david.blevins@gmail.com <ma...@gmail.com>> wrote:
>>>
>>>> On Jul 14, 2020, at 7:34 PM, David Blevins <david.blevins@gmail.com <ma...@gmail.com>> wrote:
>>>>
>>>> I think there are two gaps we need to understand to have a better conversation about using Antora
>>>>
>>>> - Eliminating the Apache CMS from our lives. This is the biggest blocker to any true progress. The only reason our site doesn't automatically update now is because we're using the Apache CMS which has a manual publish step that takes about an hour of machine time and periodic manual checking/poking during that time.
>>>>
>>>> - Understanding `tomee-site-generator` isn't an enemy to Antora and doesn't need to die or be eliminated. Among other things, we use it to generate asciidoc content when and where we can. It will most likely need to run just before Antora. Antora would be building some mix of manually created docs and some generated docs. If Antora is not capable of committing generated files to git, then `tomee-site-generator` is where we would do that work.
>>>>
>>>> I recommend we first eliminate the Apache CMS so we have a hands-free setup. Then I recommend we make it so the `tomee-site-generator` maven project is the thing that kicks off and runs Antora.
>>>
>>> I've been doing some research and have some revised thoughts on how we could potentially proceed with this.
>>>
>>> Being terse as possible so we can try to get this out of discussion/debate mode and into action mode.
>>>
>>> Many Antora users, including Antora.org <http://antora.org/> itself, seem to use this pattern and I think it's probably the one we want.
>>>
>>> - https://antora.org/ <https://antora.org/> -> Built with a general purpose tool (Middleman+Asciidoc)
>>> - https://docs.antora.org/ <https://docs.antora.org/> -> Built with Antora
>>>
>>> - https://getfedora.org/ <https://getfedora.org/> -> Built with a general purpose tool
>>> - https://docs.fedoraproject.org/ <https://docs.fedoraproject.org/> -> Built with Antora
>>>
>>> - http://pinot.apache.org/ <http://pinot.apache.org/> -> Built with a general purpose tool
>>> - https://docs.pinot.apache.org/ <https://docs.pinot.apache.org/> -> Built with GitBook
>>>
>>> - https://www.mulesoft.com/ <https://www.mulesoft.com/> -> Built with a general purpose tool
>>> - https://docs.mulesoft.com/ <https://docs.mulesoft.com/> -> Built with Antora
>>>
>>> If we did this pattern we could probably get it done by end of week:
>>>
>>> - https://tomee.apache.org/ <https://tomee.apache.org/> -> Built with tomee-site-generator as is now
>>> - https://docs.tomee.apache.org/ <https://docs.tomee.apache.org/> -> Built with Antora
>>>
>>> We would request a new repo not connected to the CMS for docs.tomee.apache.org <http://docs.tomee.apache.org/> and have David push directly to it right now. David can lead that effort and just inform us on how it goes.
>>>
>>> We would then make the "Documentation" navigation item of tomee.apache.org <http://tomee.apache.org/> point to docs.tomee.apache.org <http://docs.tomee.apache.org/>. We'd still move it off the CMS, but I'm happy to do the lifting on that.
>>>
>>> I greatly prefer this approach to either 1) endlessly debating tools or 2) holding up David's work any longer.
>>>
>>> There would still be room for debate, but that debate could happen using the staging capabilities of the git-based solution. I think we'd be in an overall better position to introduce more changes with everyone on equal footing.
>>>
>>>
>>> Thoughts?
>>>
>>>
>>> -David
>>>
>>>
>>
>
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
David Blevins and I had a long chat about the history of OpenEJB/TomEE documentation and I have a considerably different perspective now on the best way forward. I’d say the most fundamental shift is my realizing that even if doing everything with Antora is the most elegant and efficient solution, it may not be appropriate for TomEE because it involves extending the doc build system with javascript, whereas TomEE developers are more likely to be comfortable with java. Learning a new language in order to improve or even understand the doc build is too big a barrier. I’m likely to continue to see how, for instance, “marketing pages” and the tricks in the examples can be implemented in Antora, but because I want to learn how to do those things rather than because they are appropriate to use in TomEE.
I think the following steps make sense:
- versioned doc consolidation: There are now 5 copies of the “tomee” versioned docs; one in common, and 4 identical copies done by asciidoc includes. Looking at one of these includes, it’s not very obvious how to edit the page, and certainly having one copy in ‘common’ is silly. So, the “originals” should be moved to one of the versions. The obvious choices are 7.0.x and 8.0.x. 7 might make it more obvious that changing the doc will change all 4 versions, but development is most convenient on master, 8.0. To make it easiest to locate the actual source, I’ll move the ‘original’ to 8.0. I hope that there will be a period of organization and improvement of the existing content followed by writing new content. After reorganization has settled down it may make sense to replace the “include” copies with one or two actual copies in the 7.0.x and 7.1.x branches so changes in master won’t inadvertently affect older versions.
- common doc consolidation. The pages that show up in the common component come from two repos: tomee-site-generator and tomee-site. I don’t think it’s a good idea to have content in the same repo as site generator code, so I’m planning to move the content in tomee-site-generator to tomee-site. David said something indicating that this may not be an appropriate location, so perhaps a new repo would be appropriate…. I’ll investigate. Also, this content includes all the stuff that was previously in CMS and not served by the current site build. It’s apt to need a lot of editing, consolidation, etc, and it’s possible that this entire component should not be produced by Antora. However, at the moment, the only place all the content is accessible for consideration is in the Antora build, so I propose we leave it there for now, organize it, and consider what to do with it afterwards. One possibility, since Antora deals well with multiple versions, is to have something similar to the current common content minus the doc pages mentioned above as a “historical content” component version with the “current common” component version redirect to elsewhere.
- examples. I’ve accumulated a pile of asciidoc fixes for the READMEs and I’ll see about getting them back to the master branch.
- source directory structure. David pointed out that the shorter the path to the actual adoc files the more likely people are to find them…. I’ll see how much the path can be shortened.
- publishing. It’s very tempting to work hard to create a highly unified site where the Antora and non-antora pieces are indistinguishable, however that may not be the best plan here. One of the persistent problems with documentation is that no one likes to work on it. Any complexity or difficulty is likely to deter people from contributing. A unified site would need a way for all the pieces of the site build to not step on each other, which could be hard to maintain. It may well be simpler to have two sites, one containing the front page, “marketing material”, possibly eventually the “common” component, the examples, and the other the Antora generated docs. This requires more investigation but the two-site approach is very attractive as reducing “friction”.
Possibly this can lead quickly to actually getting the Antora portion of the site published soon.
Thanks,
David Jencks
> On Aug 10, 2020, at 1:44 PM, David Jencks <da...@gmail.com> wrote:
>
> The reason Antora has a separate front page is that Dan didn’t write asciidoctor-openblock <https://gitlab.com/djencks/asciidoctor-openblock>. Since I did, it’s easy to have a front page generated by Antora. He’s known about this possibility for at least 5 years, but never found the time or motivation to do it.
>
> If you have specific complaints about the front page I wrote, please air them rather than ignoring my request for feedback.
>
> Could you be extremely specific about what you want generated by Antora and what by tomee-site-generator and what by some other unnamed tool? Are there parts of the current antora preview site that you think should not be generated by Antora? (I expect to add examples to the preview shortly, but we can discuss that separately).
>
> thanks
> David Jencks
>
>> On Aug 10, 2020, at 1:09 PM, David Blevins <david.blevins@gmail.com <ma...@gmail.com>> wrote:
>>
>>> On Jul 14, 2020, at 7:34 PM, David Blevins <david.blevins@gmail.com <ma...@gmail.com>> wrote:
>>>
>>> I think there are two gaps we need to understand to have a better conversation about using Antora
>>>
>>> - Eliminating the Apache CMS from our lives. This is the biggest blocker to any true progress. The only reason our site doesn't automatically update now is because we're using the Apache CMS which has a manual publish step that takes about an hour of machine time and periodic manual checking/poking during that time.
>>>
>>> - Understanding `tomee-site-generator` isn't an enemy to Antora and doesn't need to die or be eliminated. Among other things, we use it to generate asciidoc content when and where we can. It will most likely need to run just before Antora. Antora would be building some mix of manually created docs and some generated docs. If Antora is not capable of committing generated files to git, then `tomee-site-generator` is where we would do that work.
>>>
>>> I recommend we first eliminate the Apache CMS so we have a hands-free setup. Then I recommend we make it so the `tomee-site-generator` maven project is the thing that kicks off and runs Antora.
>>
>> I've been doing some research and have some revised thoughts on how we could potentially proceed with this.
>>
>> Being terse as possible so we can try to get this out of discussion/debate mode and into action mode.
>>
>> Many Antora users, including Antora.org <http://antora.org/> itself, seem to use this pattern and I think it's probably the one we want.
>>
>> - https://antora.org/ <https://antora.org/> -> Built with a general purpose tool (Middleman+Asciidoc)
>> - https://docs.antora.org/ <https://docs.antora.org/> -> Built with Antora
>>
>> - https://getfedora.org/ <https://getfedora.org/> -> Built with a general purpose tool
>> - https://docs.fedoraproject.org/ <https://docs.fedoraproject.org/> -> Built with Antora
>>
>> - http://pinot.apache.org/ <http://pinot.apache.org/> -> Built with a general purpose tool
>> - https://docs.pinot.apache.org/ <https://docs.pinot.apache.org/> -> Built with GitBook
>>
>> - https://www.mulesoft.com/ <https://www.mulesoft.com/> -> Built with a general purpose tool
>> - https://docs.mulesoft.com/ <https://docs.mulesoft.com/> -> Built with Antora
>>
>> If we did this pattern we could probably get it done by end of week:
>>
>> - https://tomee.apache.org/ <https://tomee.apache.org/> -> Built with tomee-site-generator as is now
>> - https://docs.tomee.apache.org/ <https://docs.tomee.apache.org/> -> Built with Antora
>>
>> We would request a new repo not connected to the CMS for docs.tomee.apache.org <http://docs.tomee.apache.org/> and have David push directly to it right now. David can lead that effort and just inform us on how it goes.
>>
>> We would then make the "Documentation" navigation item of tomee.apache.org <http://tomee.apache.org/> point to docs.tomee.apache.org <http://docs.tomee.apache.org/>. We'd still move it off the CMS, but I'm happy to do the lifting on that.
>>
>> I greatly prefer this approach to either 1) endlessly debating tools or 2) holding up David's work any longer.
>>
>> There would still be room for debate, but that debate could happen using the staging capabilities of the git-based solution. I think we'd be in an overall better position to introduce more changes with everyone on equal footing.
>>
>>
>> Thoughts?
>>
>>
>> -David
>>
>>
>
Re: Making Antora actionable
Posted by David Jencks <da...@gmail.com>.
The reason Antora has a separate front page is that Dan didn’t write asciidoctor-openblock <https://gitlab.com/djencks/asciidoctor-openblock>. Since I did, it’s easy to have a front page generated by Antora. He’s known about this possibility for at least 5 years, but never found the time or motivation to do it.
If you have specific complaints about the front page I wrote, please air them rather than ignoring my request for feedback.
Could you be extremely specific about what you want generated by Antora and what by tomee-site-generator and what by some other unnamed tool? Are there parts of the current antora preview site that you think should not be generated by Antora? (I expect to add examples to the preview shortly, but we can discuss that separately).
thanks
David Jencks
> On Aug 10, 2020, at 1:09 PM, David Blevins <da...@gmail.com> wrote:
>
>> On Jul 14, 2020, at 7:34 PM, David Blevins <da...@gmail.com> wrote:
>>
>> I think there are two gaps we need to understand to have a better conversation about using Antora
>>
>> - Eliminating the Apache CMS from our lives. This is the biggest blocker to any true progress. The only reason our site doesn't automatically update now is because we're using the Apache CMS which has a manual publish step that takes about an hour of machine time and periodic manual checking/poking during that time.
>>
>> - Understanding `tomee-site-generator` isn't an enemy to Antora and doesn't need to die or be eliminated. Among other things, we use it to generate asciidoc content when and where we can. It will most likely need to run just before Antora. Antora would be building some mix of manually created docs and some generated docs. If Antora is not capable of committing generated files to git, then `tomee-site-generator` is where we would do that work.
>>
>> I recommend we first eliminate the Apache CMS so we have a hands-free setup. Then I recommend we make it so the `tomee-site-generator` maven project is the thing that kicks off and runs Antora.
>
> I've been doing some research and have some revised thoughts on how we could potentially proceed with this.
>
> Being terse as possible so we can try to get this out of discussion/debate mode and into action mode.
>
> Many Antora users, including Antora.org itself, seem to use this pattern and I think it's probably the one we want.
>
> - https://antora.org/ -> Built with a general purpose tool (Middleman+Asciidoc)
> - https://docs.antora.org/ -> Built with Antora
>
> - https://getfedora.org/ -> Built with a general purpose tool
> - https://docs.fedoraproject.org/ -> Built with Antora
>
> - http://pinot.apache.org/ -> Built with a general purpose tool
> - https://docs.pinot.apache.org/ -> Built with GitBook
>
> - https://www.mulesoft.com/ -> Built with a general purpose tool
> - https://docs.mulesoft.com/ -> Built with Antora
>
> If we did this pattern we could probably get it done by end of week:
>
> - https://tomee.apache.org/ -> Built with tomee-site-generator as is now
> - https://docs.tomee.apache.org/ -> Built with Antora
>
> We would request a new repo not connected to the CMS for docs.tomee.apache.org and have David push directly to it right now. David can lead that effort and just inform us on how it goes.
>
> We would then make the "Documentation" navigation item of tomee.apache.org point to docs.tomee.apache.org. We'd still move it off the CMS, but I'm happy to do the lifting on that.
>
> I greatly prefer this approach to either 1) endlessly debating tools or 2) holding up David's work any longer.
>
> There would still be room for debate, but that debate could happen using the staging capabilities of the git-based solution. I think we'd be in an overall better position to introduce more changes with everyone on equal footing.
>
>
> Thoughts?
>
>
> -David
>
>
Re: Making Antora actionable
Posted by David Blevins <da...@gmail.com>.
> On Jul 14, 2020, at 7:34 PM, David Blevins <da...@gmail.com> wrote:
>
> I think there are two gaps we need to understand to have a better conversation about using Antora
>
> - Eliminating the Apache CMS from our lives. This is the biggest blocker to any true progress. The only reason our site doesn't automatically update now is because we're using the Apache CMS which has a manual publish step that takes about an hour of machine time and periodic manual checking/poking during that time.
>
> - Understanding `tomee-site-generator` isn't an enemy to Antora and doesn't need to die or be eliminated. Among other things, we use it to generate asciidoc content when and where we can. It will most likely need to run just before Antora. Antora would be building some mix of manually created docs and some generated docs. If Antora is not capable of committing generated files to git, then `tomee-site-generator` is where we would do that work.
>
> I recommend we first eliminate the Apache CMS so we have a hands-free setup. Then I recommend we make it so the `tomee-site-generator` maven project is the thing that kicks off and runs Antora.
I've been doing some research and have some revised thoughts on how we could potentially proceed with this.
Being terse as possible so we can try to get this out of discussion/debate mode and into action mode.
Many Antora users, including Antora.org itself, seem to use this pattern and I think it's probably the one we want.
- https://antora.org/ -> Built with a general purpose tool (Middleman+Asciidoc)
- https://docs.antora.org/ -> Built with Antora
- https://getfedora.org/ -> Built with a general purpose tool
- https://docs.fedoraproject.org/ -> Built with Antora
- http://pinot.apache.org/ -> Built with a general purpose tool
- https://docs.pinot.apache.org/ -> Built with GitBook
- https://www.mulesoft.com/ -> Built with a general purpose tool
- https://docs.mulesoft.com/ -> Built with Antora
If we did this pattern we could probably get it done by end of week:
- https://tomee.apache.org/ -> Built with tomee-site-generator as is now
- https://docs.tomee.apache.org/ -> Built with Antora
We would request a new repo not connected to the CMS for docs.tomee.apache.org and have David push directly to it right now. David can lead that effort and just inform us on how it goes.
We would then make the "Documentation" navigation item of tomee.apache.org point to docs.tomee.apache.org. We'd still move it off the CMS, but I'm happy to do the lifting on that.
I greatly prefer this approach to either 1) endlessly debating tools or 2) holding up David's work any longer.
There would still be room for debate, but that debate could happen using the staging capabilities of the git-based solution. I think we'd be in an overall better position to introduce more changes with everyone on equal footing.
Thoughts?
-David