Yeah! Thanks! -- Andrea Cosentino ---------------------------------- Apache Camel PMC Member Apache Karaf Committer Apache Servicemix Committer Email: ancosen1...@yahoo.com Twitter: @oscerd2 Github: oscerd
On Thursday, June 9, 2016 3:43 PM, Claus Ibsen <claus.ib...@gmail.com> wrote: Hi I added so the tool will skip some modules in that check https://github.com/apache/camel/commit/9491da8f393fa95fb33cf3afcb65dab88be63f86 We can add to that list later if we find out some more do not need adoc files. On Thu, Jun 9, 2016 at 3:25 PM, Andrea Cosentino <ancosen1...@yahoo.com.invalid> wrote: > Yeah, sorry my mistake. I always forge to clean up :-) > > New list > > [WARNING] Missing document detected: 28 > [WARNING] camel-atmos > [WARNING] camel-cm-sms > [WARNING] camel-coap > [WARNING] camel-context > [WARNING] camel-core-osgi > [WARNING] camel-core-xml > [WARNING] camel-cxf-transport > [WARNING] camel-ehcache > [WARNING] camel-ejb > [WARNING] camel-gson > [WARNING] camel-http-common > [WARNING] camel-hystrix > [WARNING] camel-ignite > [WARNING] camel-jackson > [WARNING] camel-jacksonxml > [WARNING] camel-jetty > [WARNING] camel-jetty-common > [WARNING] camel-linkedin > [WARNING] camel-olingo2 > [WARNING] camel-ribbon > [WARNING] camel-salesforce > [WARNING] camel-spring-boot-starter > [WARNING] camel-spring-dm > [WARNING] camel-tarfile > [WARNING] camel-test-karaf > [WARNING] camel-test-spring > [WARNING] camel-testng > [WARNING] camel-zipkin-starter > > > -- > Andrea Cosentino > ---------------------------------- > Apache Camel PMC Member > Apache Karaf Committer > Apache Servicemix Committer > Email: ancosen1...@yahoo.com > Twitter: @oscerd2 > Github: oscerd > > > > On Thursday, June 9, 2016 3:22 PM, Claus Ibsen <claus.ib...@gmail.com> wrote: > Hi > > Great to hear we are so far away already. > > For that list there is some false alarms we can turn off, such as some > of those test modules etc. > Also the list seems to look in dirs that has been removed. > > You can try run > > git clean -d -f > > > > > On Thu, Jun 9, 2016 at 2:33 PM, Andrea Cosentino > <ancosen1...@yahoo.com.invalid> wrote: >> Currently I've migrated the biggest part of components from confluence to >> Asciidoc. >> >> Maybe there are still asciidoc file that don't have the placeholder for >> automatic generation of docs. If you find them, please commit the change and >> re-generate documentation. >> >> Using the catalog maven plugin I have the following list of missing docs for >> components: >> >> [WARNING] Missing document detected: 35 >> [WARNING] camel-atmos >> [WARNING] camel-cm-sms >> [WARNING] camel-coap >> [WARNING] camel-context >> [WARNING] camel-core-osgi >> [WARNING] camel-core-xml >> [WARNING] camel-cxf-transport >> [WARNING] camel-ehcache >> [WARNING] camel-ejb >> [WARNING] camel-gae >> [WARNING] camel-gson >> [WARNING] camel-http-common >> [WARNING] camel-hystrix >> [WARNING] camel-ignite >> [WARNING] camel-jackson >> [WARNING] camel-jacksonxml >> [WARNING] camel-jetty >> [WARNING] camel-jetty-common >> [WARNING] camel-jetty8 >> [WARNING] camel-linkedin >> [WARNING] camel-olingo2 >> [WARNING] camel-ribbon >> [WARNING] camel-salesforce >> [WARNING] camel-spring-boot-starter >> [WARNING] camel-spring-dm >> [WARNING] camel-tarfile >> [WARNING] camel-test-karaf >> [WARNING] camel-test-spring >> [WARNING] camel-test-spring3 >> [WARNING] camel-test-spring40 >> [WARNING] camel-testng >> [WARNING] camel-web >> [WARNING] camel-web-standalone >> [WARNING] camel-zipkin-starter >> >> >> Salesforce and Linkedin are splitted in two different projects API and >> component, maybe that's why we get them in the list. >> >> Anyway we are in a good situation now. Still need to move the camel-core >> components asciidoc. >> >> If you have time, you can add the asciidoc related to this list. >> >> -- >> Andrea Cosentino >> ---------------------------------- >> Apache Camel PMC Member >> Apache Karaf Committer >> Apache Servicemix Committer >> Email: ancosen1...@yahoo.com >> Twitter: @oscerd2 >> Github: oscerd >> >> >> >> On Wednesday, January 27, 2016 4:35 PM, Claus Ibsen <claus.ib...@gmail.com> >> wrote: >> On Wed, Jan 27, 2016 at 4:10 PM, Antonin Stefanutti >> <anto...@stefanutti.fr> wrote: >>> I’ve just tried it successfully for the Twitter component (both component >>> and endpoint options). >>> >>> That’d be nice to have the ability to style the description. For example >>> {@code TwitterComponent} from the Javadoc would render as an inline code >>> block in the description column. >>> >> >> Yeah such minor improvements could be good to write down. So I logged >> a ticket where we can add the good ideas >> https://issues.apache.org/jira/browse/CAMEL-9541 >> >> >> >>> Antonin >>> >>>> On 27 Jan 2016, at 14:35, Claus Ibsen <claus.ib...@gmail.com> wrote: >>>> >>>> Hi >>>> >>>> I just added support for component option as well, so its similar >>>> style. Add comments but use component instead of endpoint. >>>> >>>> And I enabled the goal to run on components/pom.xml so it runs by default >>>> now. >>>> >>>> So you should be able to try this on all the existing .adoc files. >>>> >>>> >>>> >>>> On Wed, Jan 27, 2016 at 2:33 PM, Andrea Cosentino >>>> <ancosen1...@yahoo.com.invalid> wrote: >>>>> Ok, then we'll continue to import docs and when we have enough material >>>>> we can add comments everywhere :-) >>>>> >>>>> -- >>>>> Andrea Cosentino >>>>> ---------------------------------- >>>>> Apache Camel PMC Member >>>>> Apache Karaf Committer >>>>> Email: ancosen1...@yahoo.com >>>>> Twitter: @oscerd2 >>>>> Github: oscerd >>>>> >>>>> >>>>> >>>>> On Wednesday, January 27, 2016 2:12 PM, Antonin Stefanutti >>>>> <anto...@stefanutti.fr> wrote: >>>>> >>>>>> On 27 Jan 2016, at 13:51, Claus Ibsen <claus.ib...@gmail.com> wrote: >>>>>> >>>>>> On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti >>>>>> <anto...@stefanutti.fr> wrote: >>>>>>> Yes I think we should add the comments. >>>>>>> >>>>>>> For the SJMS and Metrics components, it shows the need to be able to >>>>>>> categorise the options. Obvious categories would be 'consumer' and >>>>>>> 'producer' though for components like Metrics, some options are only >>>>>>> applicable to a certain URI remaining that are component specific. So >>>>>>> maybe an idea would be able to add categories/tags to option metadata >>>>>>> and be able to use them in documentation sections like: >>>>>>> >>>>>>> // endpoint options: START[tags=common,consumer] >>>>>>> // endpoint options: END >>>>>>> >>>>>>> // endpoint options: START[tags=common,timer] >>>>>>> // endpoint options: END >>>>>>> >>>>>>> In the spirit of what Asciidoctor provides: >>>>>>> http://asciidoctor.org/docs/user-manual/#by-tagged-regions >>>>>>> >>>>>>> It’d be great to have that as well for the headers and component >>>>>>> options. >>>>>>> >>>>>>> Antonin >>>>>>> >>>>>>>> On 27 Jan 2016, at 12:43, Andrea Cosentino >>>>>>>> <ancosen1...@yahoo.com.INVALID> wrote: >>>>>>>> >>>>>>>> Maybe we can start adding the comments >>>>>>>> >>>>>>>> // endpoint options: START >>>>>>>> // endpoint options: END >>>>>>>> >>>>>>>> on the asciidoc we've already committed. >>>>>>>> >>>>>>>> WDYT? >>>>>> >>>>>> Yeah though at first I would like to get the basics working, eg if we >>>>>> can get the table generate for endpoint and component options. The >>>>>> latter we do not yet have. >>>>>> >>>>>> Then we can ponder more about splitting the endpoint options into >>>>>> multiple tables. If there is not so many options then a single table >>>>>> is maybe better, than having 3 or more small tables with only 1 or 2 >>>>>> options. >>>>>> >>>>>> So maybe when we have a bunch of documents done with the single table, >>>>>> we can get a better "feeling". >>>>>> Today there is a "group" column that categorizes what the option is used >>>>>> for. >>>>> >>>>> Totally agree. All those tiny tables in the Metrics documentation does >>>>> not help conciseness and readability so probably better refactoring it >>>>> into a single table. >>>>> >>>>> >>>>>> >>>>>>>> -- >>>>>>>> Andrea Cosentino >>>>>>>> ---------------------------------- >>>>>>>> Apache Camel PMC Member >>>>>>>> Apache Karaf Committer >>>>>>>> Email: ancosen1...@yahoo.com >>>>>>>> Twitter: @oscerd2 >>>>>>>> Github: oscerd >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen >>>>>>>> <claus.ib...@gmail.com> wrote: >>>>>>>> Hi >>>>>>>> >>>>>>>> I worked a bit more on this and have made the plugin update the >>>>>>>> existing adoc file (if present). And I have used the camel-ahc as >>>>>>>> experiment. >>>>>>>> >>>>>>>> The online page at >>>>>>>> https://github.com/apache/camel/blob/master/components/camel-ahc/src/main/docs/ahc.adoc >>>>>>>> >>>>>>>> Has all those endpoint options generated from the source code. So if >>>>>>>> you fix a typo, or add a new option or whatever, then the >>>>>>>> documentation is automatic updated when you compile the code. >>>>>>>> >>>>>>>> Then you can just commit the doc changes together with the source code >>>>>>>> changes. >>>>>>>> >>>>>>>> >>>>>>>> To make this possible, then just add 2 comments in the .adoc file >>>>>>>> where the table should be inserted/updated. So all you do is remove >>>>>>>> the existing table, and add these 2 lines >>>>>>>> >>>>>>>> // endpoint options: START >>>>>>>> // endpoint options: END >>>>>>>> >>>>>>>> The tool can be improved to eg maybe split the table into 3 >>>>>>>> - consumer >>>>>>>> - producer >>>>>>>> - common >>>>>>>> >>>>>>>> For endpoints that supports both consumer and producers, such as file >>>>>>>> / jms etc. Then maybe its easier for end users to look at only the >>>>>>>> table they use (eg consumer or producer + common). Though all that is >>>>>>>> smaller details. >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> On Wed, Jan 27, 2016 at 8:50 AM, Andrea Cosentino >>>>>>>> <ancosen1...@yahoo.com.invalid> wrote: >>>>>>>>> Great stuff, >>>>>>>>> >>>>>>>>> Looking forward for the end of the docs migration to Asciidoc and the >>>>>>>>> integration of this in the full build process! :-) >>>>>>>>> >>>>>>>>> Andrea >>>>>>>>> >>>>>>>>> >>>>>>>>> -- >>>>>>>>> Andrea Cosentino >>>>>>>>> ---------------------------------- >>>>>>>>> Apache Camel PMC Member >>>>>>>>> Apache Karaf Committer >>>>>>>>> Email: ancosen1...@yahoo.com >>>>>>>>> Twitter: @oscerd2 >>>>>>>>> Github: oscerd >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen >>>>>>>>> <claus.ib...@gmail.com> wrote: >>>>>>>>> Hi >>>>>>>>> >>>>>>>>> I just pushed some code I started end of last year on a train ride >>>>>>>>> back when returning from x-mas holiday. >>>>>>>>> >>>>>>>>> The code is in tooling/maven/camel-package-maven-plugin where there is >>>>>>>>> a new maven goal called update-readme. >>>>>>>>> https://github.com/apache/camel/blob/master/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/ReadmeComponentMojo.java >>>>>>>>> >>>>>>>>> That goal is able to fetch all the options the Camel components from >>>>>>>>> this maven module has. And then it generates a markdown readme.md file >>>>>>>>> using mvel2 templating. >>>>>>>>> >>>>>>>>> All the options on the component and endpoint level is then dumped in >>>>>>>>> that template. This ensures the documentation is 100% up to date with >>>>>>>>> the source code. >>>>>>>>> >>>>>>>>> I enabled the goal on the camel-ahc component (the first component), >>>>>>>>> so you can try it with running: >>>>>>>>> >>>>>>>>> mvn clean install -Dtest=false >>>>>>>>> >>>>>>>>> in that directory. Currently the goal only dumps to logging, so you >>>>>>>>> see it on the console what the template generates. >>>>>>>>> >>>>>>>>> >>>>>>>>> The idea moving forward would be to adjust this to the ascii doc that >>>>>>>>> currently is being worked on. For example to update those files in the >>>>>>>>> src/main/doc directory. >>>>>>>>> >>>>>>>>> And if those ascii docs, for example has a comment start/end marker >>>>>>>>> then the maven goal can detect those and then only do its changed >>>>>>>>> there. Then we have a mix where the ascii doc is hand created at >>>>>>>>> first, and then all the options is automatic inserted/updated by the >>>>>>>>> maven goal. And if there is no changes then the file is left as-is. >>>>>>>>> >>>>>>>>> The end goal is that if you change a typo in the documentation in the >>>>>>>>> source code, then the mvn goal will update the ascii docs as well (or >>>>>>>>> markdown or what we end up selecting). >>>>>>>>> >>>>>>>>> The maven goal is still limited but at least there is a prototype to >>>>>>>>> play with and continue working on. >>>>>>>>> >>>>>>>>> Down the road we can also make the goal generate a full list of all >>>>>>>>> the components, a table like this one >>>>>>>>> http://camel.apache.org/components.html >>>>>>>>> >>>>>>>>> And then after that we can do the same for >>>>>>>>> >>>>>>>>> - languages >>>>>>>>> - data formats >>>>>>>>> - EIP patterns >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> On Fri, Jan 22, 2016 at 9:08 PM, Claus Ibsen <claus.ib...@gmail.com> >>>>>>>>> wrote: >>>>>>>>>> Hi Hiram >>>>>>>>>> >>>>>>>>>> Thanks for experimenting with this. >>>>>>>>>> >>>>>>>>>> Better documentation and ... website is something I would love to >>>>>>>>>> see happen. >>>>>>>>>> >>>>>>>>>> All the hard work we have done with making Camel components "self >>>>>>>>>> documenting" plays a part here, as we should be able to auto generate >>>>>>>>>> part of the documentation, such as all the component / endpoint >>>>>>>>>> options. And in addition the EIPs, languages, and data formats. >>>>>>>>>> >>>>>>>>>> Also we know if an endpoint options is only to be used on the >>>>>>>>>> consumer >>>>>>>>>> side or the producer etc. For example the file component has a lot of >>>>>>>>>> options, but we can make a website, where the user can see the >>>>>>>>>> options >>>>>>>>>> grouped nicely. Or even make the website a bit more interactive so >>>>>>>>>> the >>>>>>>>>> user can click "consumer" and only see the options relevant for that. >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> On Thu, Jan 21, 2016 at 4:29 PM, Hiram Chirino >>>>>>>>>> <hi...@hiramchirino.com> wrote: >>>>>>>>>>> Hi folks, >>>>>>>>>>> >>>>>>>>>>> The artemis project has been using a gitbook based tool chain to >>>>>>>>>>> generate their docs from project source that seems kinda cool. I >>>>>>>>>>> know >>>>>>>>>>> a while back we discussed moving more of our docs out of confluence >>>>>>>>>>> and have it versioned with the project source code. So a first step >>>>>>>>>>> toward that goal, I'm going to replicate that gitbook toolchain >>>>>>>>>>> setup >>>>>>>>>>> in the camel project >>>>>>>>>>> >>>>>>>>>>> Next step after that would be figuring out a good >>>>>>>>>>> conversion/migration >>>>>>>>>>> plan for the actual content. >>>>>>>>>>> >>>>>>>>>>> Expect that to show up soon. >>>>>>>>>>> >>>>>>>>>>> -- >>>>>>>>>>> Hiram Chirino >>>>>>>>>>> Engineering | Red Hat, Inc. >>>>>>>>>>> hchir...@redhat.com | fusesource.com | redhat.com >>>>>>>>>>> skype: hiramchirino | twitter: @hiramchirino >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> -- >>>>>>>>>> Claus Ibsen >>>>>>>>>> ----------------- >>>>>>>>>> http://davsclaus.com @davsclaus >>>>>>>>>> Camel in Action 2: https://www.manning.com/ibsen2 > >> >>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> -- >>>>>>>>> Claus Ibsen >>>>>>>>> ----------------- >>>>>>>>> http://davsclaus.com @davsclaus >>>>>>>>> Camel in Action 2: https://www.manning.com/ibsen2 >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> -- >>>>>>>> Claus Ibsen >>>>>>>> ----------------- >>>>>>>> http://davsclaus.com @davsclaus >>>>>>>> Camel in Action 2: https://www.manning.com/ibsen2 >>>>>>> >>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> Claus Ibsen >>>>>> ----------------- >>>>>> http://davsclaus.com @davsclaus >>>>>> Camel in Action 2: https://www.manning.com/ibsen2 >>>> >>>> >>>> >>>> -- >>>> Claus Ibsen >>>> ----------------- >>>> http://davsclaus.com @davsclaus >>>> Camel in Action 2: https://www.manning.com/ibsen2 >>> >> >> >> >> -- >> Claus Ibsen >> ----------------- >> http://davsclaus.com @davsclaus >> Camel in Action 2: https://www.manning.com/ibsen2 > > > > -- > Claus Ibsen > ----------------- > http://davsclaus.com @davsclaus > Camel in Action 2: https://www.manning.com/ibsen2 -- Claus Ibsen ----------------- http://davsclaus.com @davsclaus Camel in Action 2: https://www.manning.com/ibsen2
