Hi David, I like where this is heading, what I like the most is that the templating is done in Asciidoc based on data in the component's documentation, this feels like the right approach as it allows remixing the content as needed. For a silly example, say we wish to have a page that lists all the messaging components or all AWS components, seems to me that would be fairly easy by creating a document indexing over an attribute -- we would need to add the category or label attribute for those examples.
What I wonder though, is how do we maintain the attributes in the component Asciidoc files? You mention JSON to Asciidoc tool, would it be possible to have the Asciidoc file and JSON file side by side? There's some talk on Camel catalog, could we leverage that? That way we would have attributes in the catalog JSON file and documentation in adoc files. zoran On Tue, Apr 7, 2020 at 6:21 AM David Jencks <david.a.jen...@gmail.com> wrote: > > 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 > > -- Zoran Regvart
