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
