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.
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
