I’ve written an asciidoctor extension that queries the Antora content catalog and constructs simple reports. We might be able to use this to have Antora generate the index tables in the components component.
The basic idea is to have the documentation generator transfer some information from the json file to document attributes in the .adoc page. These are then available to use for selection or results in a query. I set up a preview of the current state of the Antora portion of the website. For some reason the hugo portion is not building for me. https://camel-preview-1.s3-us-west-2.amazonaws.com/components/latest/index.html <https://camel-preview-1.s3-us-west-2.amazonaws.com/components/latest/index.html> First on this (and the dataformat and language index pages) there’s statistics and a table generated by the extension, and then the pre-existing table for comparison. There are some glitches, but the basic idea should be evident. Some comments on the formatting: - it’s not possible to combine the xref and the artifact id into the same column. I’d have to write a much more sophisticated report generator, and I don’t think that’s appropriate. On the other hand, I like having them separate; for one thing, the fact that it’s an artifact id is labelled. - It is possible to combine the deprecated and description columns. The json>>adoc tool would do this. I’m not sure I like that idea. I do wonder if it would be useful to report “deprecated since” to give people an idea how much longer it might be around. I don’t know if this information is available. Other comments: - the languages generated table is not yet working. I haven’t found the doc codegen for it, if any. - there are some blank rows. I think these might be from “miscellaneous” components: There are two tables on the “components” index page, one for components and one for “miscellaneous components”. Earlier in automated codegen/processing these are treated independently. What’s the difference? Is the any relationship between them? Is there any reason to have them listed on the same page? - I’d suggest to split these into two pages. - The extension is capable of generating the indexes in the nav files, but that requires Allow asciidoctor extensions when processing nav files <https://gitlab.com/antora/antora/-/issues/592> which I think is unlikely to get into Antora 2.3. ——————— Here’s an example of a component .adoc header: [[activemq-component]] = ActiveMQ Component :page-source: components/camel-activemq/src/main/docs/activemq-component.adoc :artifactId: camel-activemq :description: The activemq component allows messages to be sent to (or consumed from) Apache ActiveMQ. This component extends the Camel JMS component. :since: 1.0 Here’s what the component table generation looks like in the components index.adoc: Number of Components: indexCount:[] in indexUniqueCount:[unique=artifactid] JAR artifacts (indexCount:[attributes=deprecated] deprecated) [width="100%",cols="4,3,1,2,5",options="header"] |=== | Data Format | Artifact | Since | Deprecated | Description |=== indexTable::[cells="$xref,artifactid,since,deprecated,description”] Thoughts? thanks David Jencks
