camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrea Cosentino <ancosen1...@yahoo.com.INVALID>
Subject Re: gitbook based doc generation
Date Wed, 27 Jan 2016 07:50:22 GMT
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: ancosen1985@yahoo.com
Twitter: @oscerd2
Github: oscerd



On Tuesday, January 26, 2016 7:55 PM, Claus Ibsen <claus.ibsen@gmail.com> wrote:
Hi

I just pushed some code I started end of last year on a train ride
back when returning from x-mas holiday.

The code is in tooling/maven/camel-package-maven-plugin where there is
a new maven goal called update-readme.
https://github.com/apache/camel/blob/master/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/ReadmeComponentMojo.java

That goal is able to fetch all the options the Camel components from
this maven module has. And then it generates a markdown readme.md file
using mvel2 templating.

All the options on the component and endpoint level is then dumped in
that template. This ensures the documentation is 100% up to date with
the source code.

I enabled the goal on the camel-ahc component (the first component),
so you can try it with running:

     mvn clean install -Dtest=false

in that directory. Currently the goal only dumps to logging, so you
see it on the console what the template generates.


The idea moving forward would be to adjust this to the ascii doc that
currently is being worked on. For example to update those files in the
src/main/doc directory.

And if those ascii docs, for example has a comment start/end marker
then the maven goal can detect those and then only do its changed
there. Then we have a mix where the ascii doc is hand created at
first, and then all the options is automatic inserted/updated by the
maven goal. And if there is no changes then the file is left as-is.

The end goal is that if you change a typo in the documentation in the
source code, then the mvn goal will update the ascii docs as well (or
markdown or what we end up selecting).

The maven goal is still limited but at least there is a prototype to
play with and continue working on.

Down the road we can also make the goal generate a full list of all
the components, a table like this one
http://camel.apache.org/components.html

And then after that we can do the same for

- languages
- data formats
- EIP patterns

















On Fri, Jan 22, 2016 at 9:08 PM, Claus Ibsen <claus.ibsen@gmail.com> wrote:
> Hi Hiram
>
> Thanks for experimenting with this.
>
> Better documentation and ... website is something I would love to see happen.
>
> All the hard work we have done with making Camel components "self
> documenting" plays a part here, as we should be able to auto generate
> part of the documentation, such as all the component / endpoint
> options. And in addition the EIPs, languages, and data formats.
>
> Also we know if an endpoint options is only to be used on the consumer
> side or the producer etc. For example the file component has a lot of
> options, but we can make a website, where the user can see the options
> grouped nicely. Or even make the website a bit more interactive so the
> user can click "consumer" and only see the options relevant for that.
>
>
>
> On Thu, Jan 21, 2016 at 4:29 PM, Hiram Chirino <hiram@hiramchirino.com> wrote:
>> Hi folks,
>>
>> The artemis project has been using a gitbook based tool chain to
>> generate their docs from project source that seems kinda cool.  I know
>> a while back we discussed moving more of our docs out of confluence
>> and have it versioned with the project source code.  So a first step
>> toward that goal, I'm going to replicate that gitbook toolchain setup
>> in the camel project
>>
>> Next step after that would be figuring out a good conversion/migration
>> plan for the actual content.
>>
>> Expect that to show up soon.
>>
>> --
>> Hiram Chirino
>> Engineering | Red Hat, Inc.
>> hchirino@redhat.com | fusesource.com | redhat.com
>> skype: hiramchirino | twitter: @hiramchirino
>
>
>
> --
> Claus Ibsen
> -----------------
> http://davsclaus.com @davsclaus
> Camel in Action 2: https://www.manning.com/ibsen2




-- 
Claus Ibsen
-----------------
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2

Mime
View raw message