arent we already using asciidoc? ( https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content )
Romain Manni-Bucau @rmannibucau <https://twitter.com/rmannibucau> | Blog <https://blog-rmannibucau.rhcloud.com> | Old Blog <http://rmannibucau.wordpress.com> | Github <https://github.com/rmannibucau> | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory <https://javaeefactory-rmannibucau.rhcloud.com> 2017-09-25 16:56 GMT+02:00 Andy Gumbrecht <andy...@gmx.de>: > +1 for asciidoc > > Andy Gumbrecht. > > > > On 19/09/17 10:15, Jean-Louis Monteiro wrote: > >> I totally agree that our documentation is a pain and does not help us >> first >> to right it and contributors to help. >> Each time I have to do a fix or add something it's a pain. >> >> So +1 to simplify it. >> JBake, plain asciidoc, whatever. Just something simple. >> >> -- >> Jean-Louis Monteiro >> http://twitter.com/jlouismonteiro >> http://www.tomitribe.com >> >> On Sun, Sep 17, 2017 at 8:09 AM, Romain Manni-Bucau < >> rmannibu...@gmail.com> >> wrote: >> >> +0 to have it all and sync somehow in the site build process - i like >>> having it with the code since it enables some more stuff to happen but it >>> increases contribution cost >>> -0 to have it partially to ensure we dont loose contributors >>> >>> Side note: if you import it, ensure to update all the contributor docs >>> and >>> github proxies please >>> >>> Side note 2: we can still generate doc in another project depending on >>> main >>> artifacts ;) >>> >>> Le 17 sept. 2017 05:26, "David Blevins" <david.blev...@gmail.com> a >>> écrit >>> : >>> >>> Just wrote a long description on the definition of InvocationTime and >>>> MonitoredMethods in the JMX `@Monitor` functionality and I'm reminded on >>>> how much of a pain it is to contribute to the documentation. It would >>>> be >>>> so much easier if some part of it was in the build. >>>> >>>> I'm wondering if we want some sort of docs/ directory in our main repo. >>>> Not thinking we add jbake to the main build, just the asciidoc. The >>>> >>> fancy >>> >>>> processing can still happen elsewhere. >>>> >>>> Docs like "how to contribute to the website" would stay where they are, >>>> but things like "configuring datasources" would definitely come in. >>>> We'd >>>> then follow the Tomcat approach of: >>>> >>>> - https://tomcat.apache.org/tomcat-8.5-doc/index.html < >>>> https://tomcat.apache.org/tomcat-8.5-doc/index.html> >>>> - https://tomcat.apache.org/tomcat-8.0-doc/index.html < >>>> https://tomcat.apache.org/tomcat-8.0-doc/index.html> >>>> >>>> etc. >>>> >>>> I don't think we'd need to get too fancy and do one doc base per Web >>>> Profile, Plume, etc. just this would be enough: >>>> >>>> - https://tomee.apache.org/tomee-8.0-doc/index.html < >>>> https://tomee.apache.org/tomee-8.0-doc/index.html> >>>> - https://tomee.apache.org/tomee-7.0-doc/index.html < >>>> https://tomee.apache.org/tomee-7.0-doc/index.html> >>>> - https://tomee.apache.org/tomee-1.7-doc/index.html < >>>> https://tomee.apache.org/tomee-1.7-doc/index.html> >>>> >>>> When sheldon/chatterbox come in, they'd go: >>>> >>>> - https://tomee.apache.org/sheldon-3.0-doc/index.html < >>>> https://tomee.apache.org/sheldon-3.0-doc/index.html> >>>> - https://tomee.apache.org/chatterbox-2.1-doc/index.html < >>>> https://tomee.apache.org/chatterbox-2.1-doc/index.html> >>>> >>>> I totally made up those version numbers for illustrative purposes. You >>>> get the idea. >>>> >>>> Related note, we actually have some documentation generated from the >>>> >>> build >>> >>>> and not regenerated. This page for example was entirely generated from >>>> >>> the >>> >>>> default service-jar.xml: >>>> >>>> - http://tomee.apache.org/containers-and-resources.html < >>>> http://tomee.apache.org/containers-and-resources.html> >>>> >>>> I remember doing that ages ago, like 2008-2011 range. Aside from being >>>> likely out of date, it definitely highlights the awkward relationship >>>> between the docs and the source we currently have. >>>> >>>> >>>> -- >>>> David Blevins >>>> http://twitter.com/dblevins >>>> http://www.tomitribe.com >>>> >>>> >>>> >
