On 23/04/2020 16:10, Claus Ibsen wrote:
On Wed, Apr 22, 2020 at 9:39 PM David Jencks <david.a.jen...@gmail.com> wrote:
I looked through the non-core parts of the website and see that the subprojects
generally have one or more “index tables” similar to the index tables for the
“main” components component (and now the 3.2.x version of “components”).
I think it would be nice if these all had the same format and method of
generation as the main ones. Looking briefly at the code, it’s not very clear
to me how the information gets from human effort into the table. In order to
use the “index extension” as in the “main” tables, the necessary information
has to be available as asciidoc attributes in the pages to be included. It’s
possible to do various bits of asciidoc magic so that these pages might not be
the ones in the component component, but rather wrappers around them, but it
would certainly be simpler if the info could be in the current pages.
For the main camel components, IIUC the workflow is like this:
1. A developer annotations the actual java class
2. Something extracts these annotations and constructs a <component>.json file
from the information.
It is not only annotations, it is also JavaDoc of certain classes and
some parts of pom.xml It is the GenerateMojo that assembles the json
files
https://github.com/apache/camel/blob/master/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/GenerateMojo.java#L34-L62
It calls other mojos, not sure which particular one does that.
3. In the camel maven packaging plugin UpdateReadmeMojo, this information is
extracted from the .json file and translated into suitable header attributes.
Here’s what I think I’ve discovered about the subprojects….
- Camel K: no components table, but there’s a traits list/table that could
perhaps benefit from the same sort of treatment.
- Camel Karaf: There’s a table of components that seems to be extracted from
the feature file.
— How is this feature file maintained or generated?
Manaully.
— The existing table seems to have a second line under each component name such
as 'activemq:destinationType:destinationName’ I can’t quite imagine what this
is. (this shows up in quarkus and spring-boot-starter tables also)
Its Camel endpoint syntax for using the component (eg syntax in
@UriEndpoint) eg how the component are used in endpoint uris in your
Camel routes
- Camel Kafka Connector: I don’t see any index tables
- Camel Quarkus: Index tables “just like” in main components. I haven’t
identified where the information for these comes from.
First the PrepareCatalogQuarkusMojo generates the json files for Camel
Quarkus Catalog
https://github.com/apache/camel-quarkus/blob/master/tooling/package-maven-plugin/src/main/java/org/apache/camel/quarkus/maven/PrepareCatalogQuarkusMojo.java
The Catalog metadata is then used by UpdateDocExtensionsListMojo
https://github.com/apache/camel-quarkus/blob/master/tooling/package-maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateDocExtensionsListMojo.java
to generate the adoc page.
We currently have per-extension adoc pages rather rarely, esp. when
there is some additional config option or important difference between
the given Camel Quarkus extension and the underlying Camel component,
e.g. https://camel.apache.org/camel-quarkus/latest/extensions/ahc.html
I am considering to have semi-generated extension pages for all
extensions. It would be handy to have a landing page for the links on
https://code.quarkus.io/
I hope that helps.
-- P
If you mean this table:
https://github.com/apache/camel-quarkus/blob/master/extensions/readme.adoc
There is a maven plugin that generates this table from the list of
extensions it has (components) and enrich that with data from
camel-catalog from camel v3.
>
>
- Camel Spring Boot Starters: Index tables “just like” in main components. I
haven’t identified where the information for these comes from.
If you mean this table:
https://github.com/apache/camel-spring-boot/blob/master/components-starter/README.adoc
There is a maven plugin that generates this table from the list of
component starters it has (components) and enrich that with data from
camel-catalog from camel v3.
Could experts on these subprojects explain the data flow?
——
From my current point of view, everything would be simplest if the information
about which “extensions” apply to a given component/language/data-format could be in
the json file describing it; IIUC one way for it to get there would be to add the
information to the base java class. I’d think this information might be more
generally useful, studying a component you could see, "hmm this is available in
karaf but not quarkus”. For instance, there could be a little table in each
component page showing which subprojects it applies to or is available in. I don’t
know how reliable maintaining this by hand would be or if maintenance could
plausibly be automated.
Yeah we have talked about this before about an uber camel-catalog that
has such details from all the sub projects. But each own project has
only its own information.
There is a JIRA ticket about having a webpage on the site that lists
the components and [x] for supported runtimes (sub projects).
Thanks,
David Jencks
