On Fri, Apr 10, 2020 at 6:31 PM David Jencks <david.a.jen...@gmail.com> wrote: > > 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 :-) >
Hmm how would an icon represent this that would be easily understood? On top of my mind I cant picture something that says that - only gold, silver, bronze badges. > 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. > There are 3 variations of bindy and they share some common as well. Its a hazzle to splitup the old doc into three, and therefore they point to the same doc. > 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> Delete > https://camel.apache.org/components/latest/ignite.html > <https://camel.apache.org/components/latest/ignite.html> Delete > https://camel.apache.org/components/latest/kubernetes.html > <https://camel.apache.org/components/latest/kubernetes.html> Delete > https://camel.apache.org/components/latest/openstack.html > <https://camel.apache.org/components/latest/openstack.html> Delete > https://camel.apache.org/components/latest/spring-main.html > <https://camel.apache.org/components/latest/spring-main.html> Keep > https://camel.apache.org/components/latest/spring.html > <https://camel.apache.org/components/latest/spring.html> > Keep > 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. Its not weird - A lot of the docs are auto updated and thats what we want. > > 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> -- Claus Ibsen ----------------- http://davsclaus.com @davsclaus Camel in Action 2: https://www.manning.com/ibsen2
