I finally clicked the links you kindly provided…. > On Apr 23, 2020, at 7:47 AM, Peter Palaga <ppal...@redhat.com> wrote: > > 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 > > <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 > > <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 > > <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 > <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/ <https://code.quarkus.io/>
I wonder if it would be clearer to have a quarkus page for each extension that included the plain-camel component page and either said, “this is just the same as plain camel” or “here are the differences to plain camel”? I found it a little confusing to go to the plain camel component page from the quarkus component. This would also let us generate the index table using my antora extension. > > I hope that helps. Very much, thanks! David Jencks > > -- 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
