> On Jul 14, 2020, at 7:34 PM, David Blevins <david.blev...@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
>
