search

apache / camel-kamelets

Apache Camel Kamelets Repository
https://camel.apache.org
Apache License 2.0
52 stars 71 forks source link

Tidy up kamelets docs and remove knative binding #1705

Open davsclaus opened 8 months ago

davsclaus commented 8 months ago

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 commented 8 months ago

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 commented 3 months ago

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 commented 3 months ago

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:

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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

oscerd commented 2 months ago

Yeah I fixed that but forget to update here

oscerd commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

This https://github.com/apache/camel-kamelets/commit/c31b25a830413b8d22d52f229636b790842fdf6f should fix that

oscerd commented 2 months ago

@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 -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.