tomee-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Romain Manni-Bucau <rmannibu...@gmail.com>
Subject Re: Potentially having some part of documentation in the main repo
Date Sun, 17 Sep 2017 06:09:54 GMT
+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.blevins@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
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message