You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@camel.apache.org by Charles Moulliard <ch...@gmail.com> on 2016/04/21 07:50:45 UTC

Asciidoc(tor) documentation

Hi,

The only info that I have been able to find about the migration process to
AsciiDoc is part of the contributing web page

"Most of the documentation is stored on the wiki. We are currently moving
the documentation into the code (AsciiDoc). From there it is automatically
converted to the wiki. So before editing the wiki check the code because
otherwise your changes may be lost. This transition is work-in-progress."

Do we have more info about that (jira tickets, ...) ? Is it described
somewhere how the HTML content is generated ? Do we use asciidoctor to
render the HTML document ? If this is the case, then we should mention a
link to the asciidoctor web page (user manual, writer manual) and also
indicate that we can use the asciidoctor syntax extending what is proposed
by asciidoc

Regards,
-- 
Charles Moulliard
Apache Committer & PMC / Architect @RedHat
Twitter : @cmoulliard | Blog :  http://cmoulliard.github.io

Re: Asciidoc(tor) documentation

Posted by "Walzer, Thomas" <th...@integratix.net>.

Arnaud, Charles,

here is what Claus sent to me & the list:

>>>

Hi Thomas

Just a heads up that if you find spelling mistakes and other
corrections to the Camel components, then correcting in wiki becomes
obsolete.

We keep the documentation in the source code in the javadoc for the
setter methods on the component and endpoint classes.

We use this to generate and keep documentation up to date. Though this
is not yet complete and work in progress. But eventually the Camel
documentation on the website will be generated from this that ensures
the doc is always up to date with the actual source code.

So you may want to submit PRs to fix those docs in the source code as well.

You can see the generated docs in some of the components such as
https://github.com/apache/camel/blob/master/components/camel-ahc/src/main/docs/ahc.adoc

eg the components that have a ascii doc file.

So if you look in that adoc file you can see

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

then when building the source code, then the options within that
comment section is generated from the source code. So just change the
docs in the source and the adoc is updated.

<<<

I will try to put this information into the wiki & maybe we can describe the process (updating and generating the docs) a lit bit better. We should also describe the wiki->asciidoc migration.
It would also help, if the asciidoc-documents mention that they exist in the code not in the wiki so that people do not accidently edit them there.
Sorry that it takes a while...

Cheers, Thomas.

Am 21.04.2016 um 09:49 schrieb Arnaud Deprez <ar...@gmail.com>>:

Hi,

+1.
I've made a pull request for async with servlet (see
https://github.com/apache/camel/pull/949) and I don't know how do I have to
do to update the documentation as the asciidoc doesn't exist yet. It's not
clear to me too.

Regards

On Thu, Apr 21, 2016 at 7:50 AM Charles Moulliard <ch...@gmail.com>> wrote:

Hi,

The only info that I have been able to find about the migration process to
AsciiDoc is part of the contributing web page

"Most of the documentation is stored on the wiki. We are currently moving
the documentation into the code (AsciiDoc). From there it is automatically
converted to the wiki. So before editing the wiki check the code because
otherwise your changes may be lost. This transition is work-in-progress."

Do we have more info about that (jira tickets, ...) ? Is it described
somewhere how the HTML content is generated ? Do we use asciidoctor to
render the HTML document ? If this is the case, then we should mention a
link to the asciidoctor web page (user manual, writer manual) and also
indicate that we can use the asciidoctor syntax extending what is proposed
by asciidoc

Regards,
--
Charles Moulliard
Apache Committer & PMC / Architect @RedHat
Twitter : @cmoulliard | Blog : http://cmoulliard.github.io

--
Arnaud Deprez
Software Engineer
Phone: +32 497 23 30 44
Linked'In: https://www.linkedin.com/in/deprezarnaud
Github: https://github.com/arnaud-deprez

Re: Asciidoc(tor) documentation

Posted by Arnaud Deprez <ar...@gmail.com>.

Hi,

+1.
I've made a pull request for async with servlet (see
https://github.com/apache/camel/pull/949) and I don't know how do I have to
do to update the documentation as the asciidoc doesn't exist yet. It's not
clear to me too.

Regards

On Thu, Apr 21, 2016 at 7:50 AM Charles Moulliard <ch...@gmail.com> wrote:

> Hi,
>
> The only info that I have been able to find about the migration process to
> AsciiDoc is part of the contributing web page
>
> "Most of the documentation is stored on the wiki. We are currently moving
> the documentation into the code (AsciiDoc). From there it is automatically
> converted to the wiki. So before editing the wiki check the code because
> otherwise your changes may be lost. This transition is work-in-progress."
>
> Do we have more info about that (jira tickets, ...) ? Is it described
> somewhere how the HTML content is generated ? Do we use asciidoctor to
> render the HTML document ? If this is the case, then we should mention a
> link to the asciidoctor web page (user manual, writer manual) and also
> indicate that we can use the asciidoctor syntax extending what is proposed
> by asciidoc
>
> Regards,
> --
> Charles Moulliard
> Apache Committer & PMC / Architect @RedHat
> Twitter : @cmoulliard | Blog :  http://cmoulliard.github.io
>
-- 
Arnaud Deprez
Software Engineer
Phone: +32 497 23 30 44
Linked'In: https://www.linkedin.com/in/deprezarnaud
Github: https://github.com/arnaud-deprez

Re: Asciidoc(tor) documentation

Posted by Andrea Cosentino <an...@yahoo.com.INVALID>.

Hi Thomas,

I guess we should put a message like "do not edit in confluence" when migration will be finished. For the moment we need to upgrade both side in my opinion. Same for the links.

In camel-website there are all the .adoc outside of components stuff.

For the moment the plan is to migrating all the stuff we have exported with the cxf-web project hacked by Hiram into .adoc files inside the single components folder.

When this process will be completed, we will improve the docs updating automation and maybe we will split documentation in subfolders as Claus was saying in the main thread (component, dataformat, language etc.).

In my opinion, actually, the priority is completing the components migration to .adoc, then we will refine the gitbook index, add all other stuff and start hacking the CSS (for example with scrollable tables).

Cheers
--
Andrea Cosentino
----------------------------------
Apache Camel PMC Member
Apache Karaf Committer
Apache Servicemix Committer
Email: ancosen1985@yahoo.com
Twitter: @oscerd2
Github: oscerd

On Friday, April 22, 2016 10:22 AM, "Walzer, Thomas" <th...@integratix.net> wrote:
Hi,

Shouldn't we put some warning on every component's page "do not edit in confluence"? Or on every page that is already migrated?
Right now I find it hard to get a status on what is already migrated (except components).
Shouldn't the component pages in confluence link to the new ones?
Some things are in docs/user-manual. I assume the non-component docs. But this seems to be only a portion.
Some things are in camel-core/src/main/docs. I assume the components that are in camel-core.
What's in the directory camel-website?
Is there a plan?

Cheers, Thomas.
________________________________________

Von: Andrea Cosentino <an...@yahoo.com.INVALID>
Gesendet: Donnerstag, 21. April 2016 14:05
An: dev@camel.apache.org
Betreff: Re: Asciidoc(tor) documentation

Hi all,

Actually you'll find in some components the directory src/main/docs.

Each component should have his own <component_name>.adoc in that directory.

Actually we have this project from Hiram Chirino
https://github.com/chirino/cxf-web/tree/master

we are using it to migrate the html documentation from confluence to Asciidoc (take a look at SiteExporter class).

When you'll have the complete export, you can start adding the adoc file to the missing components.

Actually We are migrating all the docs from confluence to adoc, but if I add some option to a component, usually I'm continuing to update both sides.

By adding

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

and

// component options: START
// component options: END

in your .adoc file you'll be able to have an automated mapping of the options, without the need of writing everything.

When we'll finish migrating everything, we can stop update on the confluence side.

If you more info please ask :-)

Thanks!
--
Andrea Cosentino
----------------------------------
Apache Camel PMC Member
Apache Karaf Committer
Apache Servicemix Committer
Email: ancosen1985@yahoo.com
Twitter: @oscerd2
Github: oscerd

On Thursday, April 21, 2016 7:50 AM, Charles Moulliard <ch...@gmail.com> wrote:
Hi,

The only info that I have been able to find about the migration process to
AsciiDoc is part of the contributing web page

Regards,
--
Charles Moulliard
Apache Committer & PMC / Architect @RedHat
Twitter : @cmoulliard | Blog : http://cmoulliard.github.io

Re: Asciidoc(tor) documentation

Posted by "Walzer, Thomas" <th...@integratix.net>.

Hi,

Cheers, Thomas.
________________________________________
Von: Andrea Cosentino <an...@yahoo.com.INVALID>
Gesendet: Donnerstag, 21. April 2016 14:05
An: dev@camel.apache.org
Betreff: Re: Asciidoc(tor) documentation

Hi all,

Actually you'll find in some components the directory src/main/docs.

Each component should have his own <component_name>.adoc in that directory.

Actually we have this project from Hiram Chirino
https://github.com/chirino/cxf-web/tree/master

we are using it to migrate the html documentation from confluence to Asciidoc (take a look at SiteExporter class).

When you'll have the complete export, you can start adding the adoc file to the missing components.

Actually We are migrating all the docs from confluence to adoc, but if I add some option to a component, usually I'm continuing to update both sides.

By adding

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

and

// component options: START
// component options: END

in your .adoc file you'll be able to have an automated mapping of the options, without the need of writing everything.

When we'll finish migrating everything, we can stop update on the confluence side.

If you more info please ask :-)

Thanks!
--
Andrea Cosentino
----------------------------------
Apache Camel PMC Member
Apache Karaf Committer
Apache Servicemix Committer
Email: ancosen1985@yahoo.com
Twitter: @oscerd2
Github: oscerd

On Thursday, April 21, 2016 7:50 AM, Charles Moulliard <ch...@gmail.com> wrote:
Hi,

The only info that I have been able to find about the migration process to
AsciiDoc is part of the contributing web page

Regards,
--
Charles Moulliard
Apache Committer & PMC / Architect @RedHat
Twitter : @cmoulliard | Blog : http://cmoulliard.github.io

Re: Asciidoc(tor) documentation

Posted by Andrea Cosentino <an...@yahoo.com.INVALID>.

Hi all,

Actually you'll find in some components the directory src/main/docs.

Each component should have his own <component_name>.adoc in that directory.

Actually we have this project from Hiram Chirino
https://github.com/chirino/cxf-web/tree/master

we are using it to migrate the html documentation from confluence to Asciidoc (take a look at SiteExporter class).

When you'll have the complete export, you can start adding the adoc file to the missing components.

Actually We are migrating all the docs from confluence to adoc, but if I add some option to a component, usually I'm continuing to update both sides.

By adding

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

and

// component options: START
// component options: END

in your .adoc file you'll be able to have an automated mapping of the options, without the need of writing everything.

When we'll finish migrating everything, we can stop update on the confluence side.

If you more info please ask :-)

Thanks!
--
Andrea Cosentino
----------------------------------
Apache Camel PMC Member
Apache Karaf Committer
Apache Servicemix Committer
Email: ancosen1985@yahoo.com
Twitter: @oscerd2
Github: oscerd

On Thursday, April 21, 2016 7:50 AM, Charles Moulliard <ch...@gmail.com> wrote:
Hi,

The only info that I have been able to find about the migration process to
AsciiDoc is part of the contributing web page

Regards,
--
Charles Moulliard
Apache Committer & PMC / Architect @RedHat
Twitter : @cmoulliard | Blog : http://cmoulliard.github.io