On Mon, Oct 11, 2021 at 8:07 AM David Jencks <david.a.jen...@gmail.com> wrote: > > I’ve been working on generating the spring-boot autoconfig info from the json > files generated during the spring-boot build, and the spring boot “list.adoc” > tables using the indexer extension (like the components tables are generated). > > My understanding of the spring-boot stuff is that: > > - any Camel component can be used in Spring > > - Some camel components/dataformats… can participate in spring-boot auto > configure. These components are identified as having a corresponding > camel-*-starter project in the spring-boot repo. > > - There are 3 kinds of these: > > 1. There’s (generated) java code and a generated json file > > 2. There’s generated java code but no generated json file (e.g. jasypt) > > 3. There’s no java code and no json file, just some properties files etc. > (e.g. aws-xray) > > I’m really not familiar with spring-boot or the philosophy behind it, but my > guess is that if there’s a spring-boot starter jar then spring will create a > singleton instance of something in the jar, and if there’s a json file that > will guide or describe configuring this instance with data from somewhere. > If this is roughly correct, then the 2nd and 3rd kinds correspond to > non-configurable instances. > > I’ve discovered that: > > - several components have starters that are not listed in the existing list >
Oh which ones for example is that? For Camel on Spring Boot then we only support the -starter JARs. So if there is not a starter then its not supported. And yes some of the starters are just shallow and empty/almost empty. But it's our way to curate what we support and make sense to use on Spring Boot. For Camel on Karaf its the features.xml file that defines what we support there. And ditto for Quarkus with the extensions. > - quite a few components main adoc documentation do not include the relevant > autoconfig information (even if it’s “no options”) > Most of these are linked to from the “list” page, so I’d imagine it would be > pretty confusing to follow the link and find no information about spring-boot. > > Evidently, the current process is not maintainable. > > The (new, jsonpath based) autoconfig doc generation is based on putting the > name of the appropriate json file in the main adoc file as a header attribute. > > I think we can produce something more resilient by: > > - for kinds (2) and (3), put a no-options appropriately named json file in > the starter project under src/main/docs. This will not get added to the > starter jar, unlike the properly generated json files. > > - put the corresponding header attribute in the appropriate main adoc file > > Now we should be able to do a basic check, that the number of unique json > file names from header attributes is equal to the number of json files, which > should be equal to the number of starters. This should be possible to do as > part of the website build. > > This won’t check that for instance with a starter that serves many > components, all the components will refer to the starter information, but it > will detect most or all of the problems I’v found so far. > > The preview for https://github.com/apache/camel-website/pull/644 shows how > far I’ve gotten with this: the appropriate page to look at is > https://pr-644--camel.netlify.app/camel-spring-boot/latest/list-2.html > This has, in addition to the tables of spring-boot autoconfigure-enabled > components, counts of json files used and existing (there are 5 unused), and > tables of non-spring-boot-enabled components/dataformats… > All the dataformats and languages are set up properly. There are 2 > components that aren’t spring-boot-enabled and a whole lot of “others" > > I think that actually failing the build when there are unused .json files and > also finding out which json files are unused will have to wait for an upgrade > to the antora-indexer… unfortunately this will require some syntax changes. > > I’d like to polish these changes, replace the list page with the new one > (with the extra info removed), port this work to the other relevant branches, > and then pursue releasing the upgraded antora-indexer extension and upgrading > the syntax, and then work on making the checks work. > > Does this seem reasonable? > Yeah sure continue your great work and effort on improving the documentation for all the Camel projects on the website. > —— > > Another feature of the preview is that I found out how to make the option > names in all the jsonpath generated tables link to themselves and display a > marker on hover, just like section titles, so you can now easily copy the > link to an option and paste it somewhere. (the names have been links for a > while, but there was no practical way to find out what the link was!) > > E.g. … > https://pr-644--camel.netlify.app/components/latest/amqp-component.html#_endpoint_query_option_disableReplyTo > > David Jencks -- Claus Ibsen ----------------- http://davsclaus.com @davsclaus Camel in Action 2: https://www.manning.com/ibsen2
