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
smime.p7s
Description: S/MIME cryptographic signature
