camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Walzer, Thomas" <thomas.wal...@integratix.net>
Subject Re: Asciidoc(tor) documentation
Date Thu, 21 Apr 2016 11:52:55 GMT
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 <arnaudeprez@gmail.com<mailto:arnaudeprez@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 <ch007m@gmail.com<mailto:ch007m@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


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message