Tidy up kamelets docs and remove knative binding

[davsclaus]

Kamelets are universal connectors for Camel, and we should tidy up docs and make it more user focused and less tech savy.

The knative binding stuff should be removed. This kind of docs belong in camel-k knative section.

Also it would be good later to go over kamelets and add more description what they do, and some small examples, also for the options.

[oscerd]

The main problem is understanding if we can move away from the js generation for the docs example. Because actually we're using that stuff with a template.

[oscerd]

I would like to restart the discussion on this but we need some help from @zregvart

Do you think is feasible to go away from js generation on-the-fly and have generated .adoc directly in the repository? That way we could focus on improving one/two Kamelets and see how it goes and go through all of them later. Working on the js side of thing keep things harder.

[zregvart]

Do you think is feasible to go away from js generation on-the-fly and have generated .adoc directly in the repository?

It is very much feasible, this is what we do in the Camel components documentation. This can be done in a separate Antora module and later on rename that module to the ROOT module.
Few things to consider:

• the navigation (nav.adoc) needs to be generated
• the index page needs to be generated
• for each Kamelet it's documentation needs to be generated, this template is currently the most complex one as it includes many variables fetched from the catalog
• this processing needs to be included in the build tooling (regen on build, regen on PR merge)

Also it would be good later to go over kamelets and add more description what they do, and some small examples, also for the options.

I think, this can be done today without changing the template processing, by placing a {name}-description.adoc in the ROOT/pages directory and adding a include like:

include::{name}-description.adoc[opts=optional]

To the ROOT/examples/template/kamelet-options.adoc template. And analogously for an example.

With that said, rendering the templates and having plain asciidoc files in the pages makes the documentation a bit easier to contribute to, troubleshoot and make changes to.

[oscerd]

Do you think is feasible to go away from js generation on-the-fly and have generated .adoc directly in the repository?

It is very much feasible, this is what we do in the Camel components documentation. This can be done in a separate Antora module and later on rename that module to the ROOT module. Few things to consider:

• the navigation (nav.adoc) needs to be generated
• the index page needs to be generated
• for each Kamelet it's documentation needs to be generated, this template is currently the most complex one as it includes many variables fetched from the catalog
• this processing needs to be included in the build tooling (regen on build, regen on PR merge)

Also it would be good later to go over kamelets and add more description what they do, and some small examples, also for the options.

I think, this can be done today without changing the template processing, by placing a {name}-description.adoc in the ROOT/pages directory and adding a include like:

include::{name}-description.adoc[opts=optional]

To the ROOT/examples/template/kamelet-options.adoc template. And analogously for an example.

With that said, rendering the templates and having plain asciidoc files in the pages makes the documentation a bit easier to contribute to, troubleshoot and make changes to.

Do you have eventually time to draft something we could start to hack on? Like a branch with just one adoc ported? Thanks.

[zregvart]

Do you have eventually time to draft something we could start to hack on? Like a branch with just one adoc ported? Thanks.

Unfortunately, I don't see much free time to work on this in the near term; perhaps I can find some time in a month or two...

[oscerd]

I tried to add this file https://github.com/apache/camel-kamelets/blob/main/docs/modules/ROOT/pages/aws-s3-source-description.adoc

And add the include in the template in the template kamelet-options

https://raw.githubusercontent.com/apache/camel-kamelets/main/docs/modules/ROOT/examples/template/kamelet-options.adoc

But it doesn't render yet on the website

https://camel.apache.org/camel-kamelets/next/aws-s3-source.html

@zregvart can you help on this?

[zregvart]

@oscerd the page is here: https://camel.apache.org/camel-kamelets/next/aws-s3-source-description.html

[oscerd]

Yeah I fixed that but forget to update here

[oscerd]

Ok, but the problem is it needs to be included in https://camel.apache.org/camel-kamelets/next/aws-s3-source.html

Now I should be able to include it, but I'll have to use the correct level because the website fails with

+ cd /home/jenkins/712657a4/workspace/Camel_Camel.website_main/camel-website
+ yarn checks
[check:html     ] 
[check:html     ] /home/jenkins/712657a4/workspace/Camel_Camel.website_main/camel-website/public/camel-kamelets/next/aws-s3-source-description.html
[check:html     ]   1:133  error  Title starts with the `Untitled` make sure that the Asciidoc file starts with level 1 heading  camel/title
[check:html     ] 
[check:html     ] ✖ 1 problem (1 error, 0 warnings)
ERROR: "check:html" exited with 1.

[zregvart]

If you include an .adoc file in the pages directory it'll be rendered as a single page, if you wanted to include it as a part of another page place it in the partials directory. See the docs here.

[oscerd]

But then I'll have to do something like

include::partial${name}-description.adoc[opts=optional]

and it won't resolve the name part.

[oscerd]

This c31b25a should fix that

[oscerd]

@davsclaus @zregvart this is working now and here is how it looks like: https://camel.apache.org/camel-kamelets/next/aws-s3-source.html

So it will be enough to create a file named <kamelet_name>-description.adoc in partials folder and we could enrich the documentation and maintain the autogenerated part.

So we could start improving the most prominent kamelets.