Le mar. 7 avr. 2020 à 06:21, David Jencks <david.a.jen...@gmail.com> a écrit :
> 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. > I think having a separate column is a good idea. Would it be possible to remove the "Component" which is in all cells of the first column, i.e. use "ActiveMQ" instead of "ActiveMQ Component" ? I think we should do it in the navigation bar too. If this comes from the meta model, we may want to remove this part there. Just an idea though... > - 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. > It isn't, but we could add it. Especially as we removed most of deprecated components in 3.0, so there's only one which is deprecated. However, this would need to enhance the meta-model to support that, so it's a bit of work, but definitely doable. > > Other comments: > > - the languages generated table is not yet working. I haven’t found the > doc codegen for it, if any. > The templating is done here: https://github.com/apache/camel/blob/master/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/UpdateDocComponentListMojo.java#L369-L381 > > - 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? > The term "component" is overused. Basically "others" means jars which are neither component, language or dataformat. They are usually extension to camel without being one of those main types. > - I’d suggest to split these into two pages. > Yes, a separate page would be better. > > - 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”] > So iiuc, you want to move the generation from build time with the maven plugin to an antora plugin. When this would be executed and what/where is the input for it ? Would that be during the build when building the docs module or in a different stage ? > > Thoughts? > thanks > David Jencks > > > -- ------------------------ Guillaume Nodet
