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>
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.
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.
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
* 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
* 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
So far the current state. Do you think we could still improve the
presentation somehow?
(This styling PR is underway:
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
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
WDYT? Which AsciiDoc document attributes should we add to the extension
pages?
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
