Thanks for the feedback! Combining two fields in the json into one column doesn’t make sense to me. Wouldn’t it be better to add a ‘deprecated’ state to the supportLevel state machine? IIUC there’s an idea to replace the words in the support level column with an icon so the wording may not matter too much, e.g. the name of the state could be stable-deprecated. It would certainly be great if there were fewer columns :-)
I don’t understand your ideas about bindy. The current site has three links to exactly the same page. I think that is excessively confusing. If there are really three flavors of bindy that ought to be explained differently, then IMO there ought to be three .adoc pages, one for each. The table generation I’m using works off of pages, not json files, so there’s no way to get three links to the same page. I might be able to produce 2 extra page aliases to the one page and have links to them, but that’s silly. With regard to the 6 json-less miscellaneous pages, I think either they should be linked to from somewhere obvious or removed completely. They aren’t just folders, there are actual pages linked to, that someone wrote. Here are the pages in the current website. They are linked to from the nav menu but not in any table. Please look at them and decide if they are current and useful or obsolete and should be removed. https://camel.apache.org/components/latest/azure.html <https://camel.apache.org/components/latest/azure.html> https://camel.apache.org/components/latest/ignite.html <https://camel.apache.org/components/latest/ignite.html> https://camel.apache.org/components/latest/kubernetes.html <https://camel.apache.org/components/latest/kubernetes.html> https://camel.apache.org/components/latest/openstack.html <https://camel.apache.org/components/latest/openstack.html> https://camel.apache.org/components/latest/spring-main.html <https://camel.apache.org/components/latest/spring-main.html> https://camel.apache.org/components/latest/spring.html <https://camel.apache.org/components/latest/spring.html> If these are current, maintained, summary pages that should be kept, then I’d suggest linking to them from each related component that they summarize. They should also be renamed so as to end up in the main components nav as they certainly don’t refer to “other” components. To merge in Guillaume's comments back into the same thread… I’ll see if I can find a plausible way to shorten some of the columns. I know about the wide/narrow button, but wide is going to remove the “on this page” TOC that I hope gets merged in soon, and narrow doesn’t use most of the actual screen space, at least on my display. The code in UpdateReadmeMojo seems rather peculiar to me, I’m going to see if I can simplify it a bit to put all the header generation in one method. In general it seems to me that it should not be trying to lint the adoc source and update it; it should perhaps find peculiar usages and perhaps fail, but auto-updating is weird. Thanks! David Jencks > On Apr 9, 2020, at 11:40 PM, Claus Ibsen <claus.ib...@gmail.com> wrote: > > On Fri, Apr 10, 2020 at 7:58 AM David Jencks <david.a.jen...@gmail.com > <mailto:david.a.jen...@gmail.com>> wrote: >> >> I have most of the basic work for this done. I’ve pushed a preview of the >> current state of the Antora generated site to >> https://camel-preview-1.s3-us-west-2.amazonaws.com/components/latest/others/index.html >> >> <https://camel-preview-1.s3-us-west-2.amazonaws.com/components/latest/others/index.html> >> >> <https://camel-preview-1.s3-us-west-2.amazonaws.com/components/latest/others/index.html >> >> <https://camel-preview-1.s3-us-west-2.amazonaws.com/components/latest/others/index.html>> >> (the new page). >> >> The source is in branches named issue-14874-generate-index-tables in >> https://github.com/djencks/camel-website.git >> <https://github.com/djencks/camel-website.git> and >> https://github.com/djencks/camel.git <https://github.com/djencks/camel.git>. >> >> As a side note, i’ve left the website playbook set up to build from the “PR >> branch” (although there’s no PR yet). With the new playbook organization >> this is really easy. >> >> Mostly old and new tables line up well. >> > > Great work David. I like the new table layout. One suggestion would be > to remove the deprecated column, and instead add that to the Support > Level column, so it would say: Stable (Deprecated) instead. As I think > it takes up to much empty space by default mode (not wide) and 99% of > the components will not be deprecated. > > Also this may have too much "noise" between the component name and the > description - that the most needed information for end users, to see > the list and find out what they do. Then information about "since" is > a bit secondary - but a great detail to see how "new the component > is". > > >> There are 6 “miscellaneous” components that appeared and don’t seem to have >> json files to extract attributes from. mostly they look like summary pages >> for collections of related components. AFAICT they aren’t linked to in the >> current site. What should happen to them? In the (new) miscellaneous table >> they have nothing outside the first column. I don’t know what to do with >> these, and without advice I’m just going to leave them. >> > > They are empty folders to group components, and should be skipped in > the table. In other words if there is no json metadata then they > should not be included. > In the future we would move for example the AWS components into its > own "folder" instead of having 20+ in the components folder. > >> In Dataformats, there’s now one one Bindy row instead of 3. Since all the >> old rows linked to the same document, same position, I think this is fine. >> > > Ah yeah bindy is a bit special as it has 3 dataformats out of the box, > and there should be 3 json files in its JAR. In other words "forget > about folders" but work with the json files - they are the source of > truth. > https://github.com/apache/camel/tree/master/components/camel-bindy/src/generated/resources/org/apache/camel/dataformat/bindy > > <https://github.com/apache/camel/tree/master/components/camel-bindy/src/generated/resources/org/apache/camel/dataformat/bindy> > >> Languages line up exactly AFAICT. >> >> There are a couple new rows in components according to the count, but I >> haven’t found them yet. >> >> A couple of other comments: >> >> - On my laptop, the table does not make good use of the page width. It’s >> centered, crammed into the middle of the screen, too narrow, and with >> gigantic left margin. >> >> - I believe the Antora default UI makes sure that the navigation item >> corresponding to the current page is visible when you click on it. This >> doesn’t seem to be working for me, it goes to the top of the nav list. This >> is pretty confusing for me. >> >> Comments very welcome. >> >> David Jencks >> >> >>> On Apr 7, 2020, at 10:20 AM, David Jencks <david.a.jen...@gmail.com >>> <mailto:david.a.jen...@gmail.com>> wrote: >>> >>> 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 >>>> <mailto:anco...@gmail.com> <mailto:anco...@gmail.com >>>> <mailto: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 >>>> <mailto:claus.ib...@gmail.com> <mailto:claus.ib...@gmail.com >>>> <mailto: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 >>>>> <mailto:zo...@regvart.com> <mailto:zo...@regvart.com >>>>> <mailto: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 >>>>>> <mailto:david.a.jen...@gmail.com> <mailto:david.a.jen...@gmail.com >>>>>> <mailto: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> >>>>> >>>>> <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>> >>>>> < >>>>> 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 >>>>> >>> >> > > > -- > Claus Ibsen > ----------------- > http://davsclaus.com <http://davsclaus.com/> @davsclaus > Camel in Action 2: https://www.manning.com/ibsen2 > <https://www.manning.com/ibsen2>
