I pushed a preview of todays state to (e.g.) 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>. Source is in my branches.
I revamped the adoc code updating so that there are two steps: - the top of the file consisting of the id, title, and attributes is written in one block. Any data present here is used in the rest of the doc, such as since and the Component producer/consumer string. (this collapses many previous methods into one) - writing the table of options (maybe there’s more, I didn’t look). I took the name of the type of item out of the index table and nav (“Component”, “DataFormat” etc) I added the deprecation notice to supportLevel. IMO this should be done by introducing a “deprecated” support level. I’m not sure where this would be. Something in the inline-styles extension, possibly combined with the tables extension, is overriding the set column widths for these tables. The result is awful. I disabled these extensions in the preview site. — Left to do: The “empty” lines in the miscellaneous table fall into two groups: - The Spring-main page. https://camel-preview-1.s3-us-west-2.amazonaws.com/components/latest/others/spring-main.html <https://camel-preview-1.s3-us-west-2.amazonaws.com/components/latest/others/spring-main.html> This looks to me like a candidate for removal. Either that or someone should add some meaningful content. — summary pages for groups of regular components. The Kubernetes page seems well designed and has links both ways from the summary to the individual pages. I plan to move these back to the main components page by renaming them <foo>-summary.adoc. I don’t think they should appear in the index table. I do think they should appear in the nav, at the head of all the pages they summarize. Possibly I’ll be able to make the summarized pages a sublist of the summary. - there are a bunch of broken links, many from the old tables that I haven’t removed yet. — Not part of this issue IMO - replacing the text supportLevel with an icon + tooltip. If we had the icons I can modify or point out how to modify the attribute generation to display them, but I don’t plan to find or design the icons. It would be really good if someone could review the changes I made to UpdateReadmeMojo. Other than the “empty” lines and the broken links, I think this is just about done. When done, I plan to squash into probably 3 commits: Mojo changes, structural changes, and generated changes. Hopefully this will be possible :-) Comments? David Jencks > On Apr 10, 2020, at 9:31 AM, 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 :-) > > 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 >> <mailto: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 >>>>>> >>>>>> <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>
