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
