gitbook based doc generation

classic Classic list List threaded Threaded
31 messages Options
12
Reply | Threaded
Open this post in threaded view
|

gitbook based doc generation

Hiram Chirino
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.
[hidden email] | fusesource.com | redhat.com
skype: hiramchirino | twitter: @hiramchirino
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Andrea Cosentino-2
Hi Hiram,

Great! Thanks!

--
Andrea Cosentino
----------------------------------
Apache Camel PMC Member
Apache Karaf Committer
Email: [hidden email]
Twitter: @oscerd2
Github: oscerd




On Thursday, January 21, 2016 4:29 PM, Hiram Chirino <[hidden email]> 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.
[hidden email] | fusesource.com | redhat.com
skype: hiramchirino | twitter: @hiramchirino
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Hiram Chirino
I took a crack at converting one of the wiki pages, the JMS component
reference. Seems like we can automate most of the work of exporting to
asciidoc format.  I used the cxf-web tool [1] to export all the pages
with a template which only includes the body content.  Then ran
`pandoc --from html --to asciidoc` on that exported content and it
produced an asciidoc which is ALMOST right.  Seem like it messes up a
little with the code sections.  Then I did a few search and replace to
clean it up.  Also all the links will need to reviewed as things will
likely move around.

I hooked up the page it generated into the gitbook generation.  I
guess it would be nice if we could also render that component page and
include it as .html file in the component .jar file.  Not 100% sure
yet how to do that.  Any thoughts on how to improve this process?


[1]: https://svn.apache.org/repos/asf/cxf/web


On Thu, Jan 21, 2016 at 10:44 AM, Andrea Cosentino
<[hidden email]> wrote:

> Hi Hiram,
>
> Great! Thanks!
>
> --
> Andrea Cosentino
> ----------------------------------
> Apache Camel PMC Member
> Apache Karaf Committer
> Email: [hidden email]
> Twitter: @oscerd2
> Github: oscerd
>
>
>
>
> On Thursday, January 21, 2016 4:29 PM, Hiram Chirino <[hidden email]> 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.
> [hidden email] | fusesource.com | redhat.com
> skype: hiramchirino | twitter: @hiramchirino



--
Hiram Chirino
Engineering | Red Hat, Inc.
[hidden email] | fusesource.com | redhat.com
skype: hiramchirino | twitter: @hiramchirino
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Claus Ibsen-2
In reply to this post by Hiram Chirino
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 <[hidden email]> 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.
> [hidden email] | fusesource.com | redhat.com
> skype: hiramchirino | twitter: @hiramchirino



--
Claus Ibsen
-----------------
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Carl Nygard
For what it's worth, I've integrated gitbook into my maven build with the
help of a docker container:

            <plugin>
              <artifactId>maven-antrun-plugin</artifactId>
              <version>${maven-antrun-plugin.version}</version>
              <executions>
                <execution>
                  <id>gitbook-pdf</id>
                  <phase>prepare-package</phase>
                  <goals>
                    <goal>run</goal>
                  </goals>
                  <configuration>
                    <target>
                      <exec executable="docker">
                        <arg value="run"/>
                        <arg value="--rm"/>
                        <arg value="--name"/>
                        <arg value="gitbook-docs"/>
                        <arg value="-v"/>
                        <arg
value="${project.build.resourcepath}/md:/usr/src/app"/>
                        <arg value="cjnygard/gitbook-docker"/>
                        <arg value="pdf"/>
                      </exec>
                    </target>
                  </configuration>
                </execution>

See https://github.com/cjnygard/gitbook-docker for the Dockerfile setup,
and https://hub.docker.com/r/cjnygard/gitbook-docker/ on Docker Hub (not
sure why it's not pulling the README.md from github though)

--carl

On Fri, Jan 22, 2016 at 3:08 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]>
> 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.
> > [hidden email] | fusesource.com | redhat.com
> > skype: hiramchirino | twitter: @hiramchirino
>
>
>
> --
> Claus Ibsen
> -----------------
> http://davsclaus.com @davsclaus
> Camel in Action 2: https://www.manning.com/ibsen2
>
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Claus Ibsen-2
In reply to this post by Claus Ibsen-2
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 <[hidden email]> 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 <[hidden email]> 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.
>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Andrea Cosentino-2
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: [hidden email]
Twitter: @oscerd2
Github: oscerd



On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Claus Ibsen-2
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
<[hidden email]> 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: [hidden email]
> Twitter: @oscerd2
> Github: oscerd
>
>
>
> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Andrea Cosentino-2
Maybe we can start adding the comments


 --
Andrea Cosentino
----------------------------------
Apache Camel PMC Member
Apache Karaf Committer
Email: [hidden email]
Twitter: @oscerd2
Github: oscerd



On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
<[hidden email]> 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: [hidden email]
> Twitter: @oscerd2
> Github: oscerd
>
>
>
> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Andrea Cosentino-2
In reply to this post by Claus Ibsen-2
Maybe we can start adding the comments

// endpoint options: START
// endpoint options: END

on the asciidoc we've already committed.

WDYT?
--
Andrea Cosentino
----------------------------------
Apache Camel PMC Member
Apache Karaf Committer
Email: [hidden email]
Twitter: @oscerd2
Github: oscerd



On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
<[hidden email]> 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: [hidden email]
> Twitter: @oscerd2
> Github: oscerd
>
>
>
> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

astefanutti
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 <[hidden email]> wrote:
>
> Maybe we can start adding the comments
>
> // endpoint options: START
> // endpoint options: END
>
> on the asciidoc we've already committed.
>
> WDYT?
> --
> Andrea Cosentino
> ----------------------------------
> Apache Camel PMC Member
> Apache Karaf Committer
> Email: [hidden email]
> Twitter: @oscerd2
> Github: oscerd
>
>
>
> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
> <[hidden email]> 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: [hidden email]
>> Twitter: @oscerd2
>> Github: oscerd
>>
>>
>>
>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>> [hidden email] | 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

Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Claus Ibsen-2
In reply to this post by Andrea Cosentino-2
On Wed, Jan 27, 2016 at 12:42 PM, Andrea Cosentino
<[hidden email]> wrote:
> Maybe we can start adding the comments
>

Yeah we could try that, basically move the plugin from camel-ahc to
the components/pom.xml so it runs for all those components.

It only do changes if there is an .adoc file and that it has those
comments. Then you can try one of the existing .adoc components and
see if you can get that to work.


>
>  --
> Andrea Cosentino
> ----------------------------------
> Apache Camel PMC Member
> Apache Karaf Committer
> Email: [hidden email]
> Twitter: @oscerd2
> Github: oscerd
>
>
>
> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
> <[hidden email]> 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: [hidden email]
>> Twitter: @oscerd2
>> Github: oscerd
>>
>>
>>
>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Claus Ibsen-2
In reply to this post by astefanutti
On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti
<[hidden email]> 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 <[hidden email]> 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.

>> --
>> Andrea Cosentino
>> ----------------------------------
>> Apache Camel PMC Member
>> Apache Karaf Committer
>> Email: [hidden email]
>> Twitter: @oscerd2
>> Github: oscerd
>>
>>
>>
>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
>> <[hidden email]> 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: [hidden email]
>>> Twitter: @oscerd2
>>> Github: oscerd
>>>
>>>
>>>
>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

astefanutti

> On 27 Jan 2016, at 13:51, Claus Ibsen <[hidden email]> wrote:
>
> On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti
> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>> Twitter: @oscerd2
>>> Github: oscerd
>>>
>>>
>>>
>>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
>>> <[hidden email]> 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: [hidden email]
>>>> Twitter: @oscerd2
>>>> Github: oscerd
>>>>
>>>>
>>>>
>>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>>>> [hidden email] | 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

Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Andrea Cosentino-2
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: [hidden email]
Twitter: @oscerd2
Github: oscerd



On Wednesday, January 27, 2016 2:12 PM, Antonin Stefanutti <[hidden email]> wrote:

> On 27 Jan 2016, at 13:51, Claus Ibsen <[hidden email]> wrote:
>
> On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti
> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>> Twitter: @oscerd2
>>> Github: oscerd
>>>
>>>
>>>
>>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
>>> <[hidden email]> 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: [hidden email]
>>>> Twitter: @oscerd2
>>>> Github: oscerd
>>>>
>>>>
>>>>
>>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Claus Ibsen-2
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
<[hidden email]> 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: [hidden email]
> Twitter: @oscerd2
> Github: oscerd
>
>
>
> On Wednesday, January 27, 2016 2:12 PM, Antonin Stefanutti <[hidden email]> wrote:
>
>> On 27 Jan 2016, at 13:51, Claus Ibsen <[hidden email]> wrote:
>>
>> On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti
>> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>>> Twitter: @oscerd2
>>>> Github: oscerd
>>>>
>>>>
>>>>
>>>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
>>>> <[hidden email]> 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: [hidden email]
>>>>> Twitter: @oscerd2
>>>>> Github: oscerd
>>>>>
>>>>>
>>>>>
>>>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>>>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

astefanutti
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 <[hidden email]> 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
> <[hidden email]> 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: [hidden email]
>> Twitter: @oscerd2
>> Github: oscerd
>>
>>
>>
>> On Wednesday, January 27, 2016 2:12 PM, Antonin Stefanutti <[hidden email]> wrote:
>>
>>> On 27 Jan 2016, at 13:51, Claus Ibsen <[hidden email]> wrote:
>>>
>>> On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti
>>> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>>>> Twitter: @oscerd2
>>>>> Github: oscerd
>>>>>
>>>>>
>>>>>
>>>>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
>>>>> <[hidden email]> 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: [hidden email]
>>>>>> Twitter: @oscerd2
>>>>>> Github: oscerd
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>>>>>> [hidden email] | 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

Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Claus Ibsen-2
On Wed, Jan 27, 2016 at 4:10 PM, Antonin Stefanutti
<[hidden email]> 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 <[hidden email]> 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
>> <[hidden email]> 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: [hidden email]
>>> Twitter: @oscerd2
>>> Github: oscerd
>>>
>>>
>>>
>>> On Wednesday, January 27, 2016 2:12 PM, Antonin Stefanutti <[hidden email]> wrote:
>>>
>>>> On 27 Jan 2016, at 13:51, Claus Ibsen <[hidden email]> wrote:
>>>>
>>>> On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti
>>>> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>>>>> Twitter: @oscerd2
>>>>>> Github: oscerd
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
>>>>>> <[hidden email]> 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: [hidden email]
>>>>>>> Twitter: @oscerd2
>>>>>>> Github: oscerd
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>>>>>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Andrea Cosentino-2
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: [hidden email]
Twitter: @oscerd2
Github: oscerd



On Wednesday, January 27, 2016 4:35 PM, Claus Ibsen <[hidden email]> wrote:
On Wed, Jan 27, 2016 at 4:10 PM, Antonin Stefanutti
<[hidden email]> 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 <[hidden email]> 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
>> <[hidden email]> 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: [hidden email]
>>> Twitter: @oscerd2
>>> Github: oscerd
>>>
>>>
>>>
>>> On Wednesday, January 27, 2016 2:12 PM, Antonin Stefanutti <[hidden email]> wrote:
>>>
>>>> On 27 Jan 2016, at 13:51, Claus Ibsen <[hidden email]> wrote:
>>>>
>>>> On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti
>>>> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>>>>> Twitter: @oscerd2
>>>>>> Github: oscerd
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
>>>>>> <[hidden email]> 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: [hidden email]
>>>>>>> Twitter: @oscerd2
>>>>>>> Github: oscerd
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>>>>>>> [hidden email] | 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
Reply | Threaded
Open this post in threaded view
|

Re: gitbook based doc generation

Claus Ibsen-2
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
<[hidden email]> 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: [hidden email]
> Twitter: @oscerd2
> Github: oscerd
>
>
>
> On Wednesday, January 27, 2016 4:35 PM, Claus Ibsen <[hidden email]> wrote:
> On Wed, Jan 27, 2016 at 4:10 PM, Antonin Stefanutti
> <[hidden email]> 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 <[hidden email]> 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
>>> <[hidden email]> 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: [hidden email]
>>>> Twitter: @oscerd2
>>>> Github: oscerd
>>>>
>>>>
>>>>
>>>> On Wednesday, January 27, 2016 2:12 PM, Antonin Stefanutti <[hidden email]> wrote:
>>>>
>>>>> On 27 Jan 2016, at 13:51, Claus Ibsen <[hidden email]> wrote:
>>>>>
>>>>> On Wed, Jan 27, 2016 at 1:07 PM, Antonin Stefanutti
>>>>> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>>>>>> Twitter: @oscerd2
>>>>>>> Github: oscerd
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On Wednesday, January 27, 2016 11:25 AM, Claus Ibsen <[hidden email]> 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
>>>>>>> <[hidden email]> 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: [hidden email]
>>>>>>>> Twitter: @oscerd2
>>>>>>>> Github: oscerd
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
>>>>>>>>>> [hidden email] | 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
12