Hi Peter, inline also! > On May 25, 2020, at 3:45 AM, Peter Palaga <ppal...@redhat.com> wrote: > > Hi David, inline... > > On 17/05/2020 20:04, David Jencks wrote: >> 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><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> >>> >>> <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> >>> >>> <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> >>> <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/> >>> <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. > > Since a week or so, we have separate pages for all our Camel Quarkus > extensions. Not sure you refer to the state before or after that change.
Before! This is pretty much exactly what I was hoping for, very nice! > > Here a couple of examples: > > * AMQ has no Camel Quarkus specific config or limitations, so the page is > very simple. Actually it is 100% generated from pom.xml and Camel Catalog: > https://camel.apache.org/camel-quarkus/latest/extensions/activemq.html > <https://camel.apache.org/camel-quarkus/latest/extensions/activemq.html> > * MP metrics has some Camel Quarkus specific behavior, so it contains some > manually maintained text blocks: > https://camel.apache.org/camel-quarkus/latest/extensions/microprofile-metrics.html > > <https://camel.apache.org/camel-quarkus/latest/extensions/microprofile-metrics.html> > * Similarly CouchDB has some Camel Quarkus specific limitations that are > added as a manually maintained block into otherwise generated content: > https://camel.apache.org/camel-quarkus/latest/extensions/couchdb.html > <https://camel.apache.org/camel-quarkus/latest/extensions/couchdb.html> > > So far the current state. Do you think we could still improve the > presentation somehow? It’s pretty nice already, but I’ve only had a quick look. > > (This styling PR is underway: > https://github.com/apache/camel-website/pull/368 > <https://github.com/apache/camel-website/pull/368> ) > >> This would also let us generate the index table using my antora extension. > > I am very much interested to give it a try, because the build time generated > list of extensions we have now > https://github.com/apache/camel-quarkus/blob/master/docs/modules/ROOT/pages/list-of-camel-quarkus-extensions.adoc > > <https://github.com/apache/camel-quarkus/blob/master/docs/modules/ROOT/pages/list-of-camel-quarkus-extensions.adoc> > is a common source of merge problems. Moving the generation of this list to > Antora might save us some rebasing in the future. > > However, I wonder whether our new extension pages can serve as a base for > your Antora extension: they are per Camel Quarkus extension, not per Camel > component. One Camel Quarkus extension can entail multiple Camel bits. E.g. > Camel Quarkus Core brings support for seven Camel languages: > https://camel.apache.org/camel-quarkus/latest/extensions/core.html > <https://camel.apache.org/camel-quarkus/latest/extensions/core.html> > WDYT? Which AsciiDoc document attributes should we add to the extension pages? From a quick look, it should be pretty easy to put what’s needed in the extension pages as attributes. Let me study it some more and see if I can come up with a proposal. I like the idea of a template for the overall page structure into which fit the custom pieces. It’s just possible that there will soon be a way to do this in an asciidoctor extension… this is giving me ideas :-) I wonder if this idea would benefit other camel sub-projects; it seems an easy way to assure that all pages have a consistent structure. There are couple of inconsistencies with at least some other parts of camel. I’m not sure if these are important or not. - page id is set to artifactIdBase whereas I think it’s generally the same as name. - other parts (e.g. base camel) use mvel as the template engine rather than Freemarker used here. I’ve never used either before, and both seem reasonable, but it might be good to only use one. Thanks, David Jencks > > Thanks, > > -- Peter > > >>> >>> 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
