This is a bit of a multi-threaded reply :-)
Guillaume asked about when this would happen.
There are two stages.
1. The already existing use of UpdateReadmeMojo.java to copy info from json
into the component (etc) adoc pages is extended to put suitable attributes into
the doc header. (I think this answers one of Zoran’s questions also)
2. The website Antora build uses the extension to query this info and build the
summary and table. There could be also a “sub-site for latest” playbook in the
docs master branch to build all the “latest” components, that could also use
this. In any case, it occurs when Antora builds a site.
The result is a static page, just like now, but with tables generated from
what’s in the content catalog, rather than directly from what’s in some json
files. (the options tables in the individual component pages are still
generated from the json files). The “generate summary tables on index pages”
mojo wouldn’t be needed any more, and the explicitly visible list of components
in the current index page would be removed. I left it in for the preview for
easy comparison.
Other questions/answers:
- The link text in the first column is the target page doctitle. Right now,
eliminating “component” from that would involve renaming the pages from e.g.
“ActiveMQ Component” to “ActiveMQ”. Would that be reasonable? If not, I
hadn’t previously considered it, but I supposed I could introduce some fancier
syntax to use another doc attribute as the link text. That would introduce a
slightly redundant attribute to every page, for instance along with the doc
title ‘= ActiveMQ Component’ there’d be ‘:link-text: ActiveMQ’. I suppose the
title could use the attribute: ‘= {link-text} Component’.
- I think the catalog labels mentioned are in the individual component json
files. If so, it would be very easy to turn them into .adoc attributes and
then put them into a column in the Antora generated table. However, it’s still
static html. Making it more interactive is making it less of a static site, at
which I am not an expert :-) I can think of two approaches: one is to
generate a lot of static tables and hide most of them, which would fit with
using this extension. The other is to generate some data, presumably as json
included in the page, and have some client side javascript to filter based on
fields and render the table into html on the client. If there’s strong support
for this latter idea I might be able to add a processor to the extension to
generate the json. I’m not sure I want to learn how to generate the tables at
runtime, someone else might need to do that. I’d suggest doing this later
after what I’m proposing now has stabilized.
- It might also be possible to have a sort-by parameter for the extension so
the components are sorted by, for example, label and then name. We’re rapidly
getting into complex report generation here :-) For instance the labels could
be turned into a list, and for each item a table with the components with that
label value. And the producer/consumer info could be shown somehow…. For me,
something like this would be a lot easier than a client-side table renderer.
I hope that answers all the questions so far.
Thanks,
David Jencks
> On Apr 7, 2020, at 2:41 AM, Andrea Cosentino <anco...@gmail.com> wrote:
>
> Maybe we can also review the labels a bit and reducing the number
>
> Il mar 7 apr 2020, 11:40 Claus Ibsen <claus.ib...@gmail.com> ha scritto:
>
>> Hi
>>
>> I would like to see the webpage be more interactive, in terms of we
>> have a fixed set of labels to quickly filter the component list.
>> So you can chose "cloud" or "database" or "file" etc.
>>
>> We have those labels today in the camel-catalog.
>>
>>
>>
>>
>> On Tue, Apr 7, 2020 at 11:31 AM Zoran Regvart <zo...@regvart.com> wrote:
>>>
>>> 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
>>
>>
>>
>> --
>> Claus Ibsen
>> -----------------
>> http://davsclaus.com @davsclaus
>> Camel in Action 2: https://www.manning.com/ibsen2
>>
