You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@camel.apache.org by David Jencks <da...@gmail.com> on 2020/04/07 04:21:00 UTC
[Website] Possibility to generate component, data format, languages
index tables
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
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by Guillaume Nodet <gn...@apache.org>.
Le mar. 7 avr. 2020 à 06:21, David Jencks <da...@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
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by Guillaume Nodet <gn...@apache.org>.
Le ven. 10 avr. 2020 à 07:58, David Jencks <da...@gmail.com> a
écrit :
> 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>
> (the new page).
>
> The source is in branches named issue-14874-generate-index-tables in
> https://github.com/djencks/camel-website.git and
> 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.
>
> 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.
>
> 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.
>
> 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 can see a "Wide / Narrow" link on the top right just above the page
content which seems to change the width of the table.
>
> - 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.
>
Looks good. I see the components are listed in the new tables as "ActiveMQ
Component", so they all end with "Component". It does not appear to be the
case in the current web site. For a page title, I think it's good to have
"ActiveMQ Component", but when listing them all in a table, it's a bit
redundant.
Otherwise looks good. Thx
>
> David Jencks
>
>
> > On Apr 7, 2020, at 10:20 AM, David Jencks <da...@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 <ancosen@gmail.com
> <ma...@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.ibsen@gmail.com <mailto:
> claus.ibsen@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 <zoran@regvart.com
> <ma...@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.jencks@gmail.com
> <ma...@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
> >>>>
> >>>>>
> >>>>> 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
> >>>
> >
>
>
--
------------------------
Guillaume Nodet
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by Claus Ibsen <cl...@gmail.com>.
Hi David
Yeah its an improvement and thank for the core vs non-core components.
On Wed, Apr 15, 2020 at 11:37 PM David Jencks <da...@gmail.com> wrote:
>
> I’ve supplied PRs for CAMEL-14906 <https://issues.apache.org/jira/browse/CAMEL-14906> and CAMEL-14907 <https://issues.apache.org/jira/browse/CAMEL-14907>.
>
> I put up a preview showing both these changes:
>
> https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html#_components_data_formats_languages_and_enterprise_integration_patterns
>
>
> 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>
>
> Are these improvements?
>
> Somehow the component counts disappeared from the previous commits, so if 14907 is rejected they’ll need to be added back.
>
> Thanks
> David Jencks
>
> > On Apr 14, 2020, at 9:21 PM, David Jencks <da...@gmail.com> wrote:
> >
> > Having closed the issue for this, CAMEL-14874 <https://issues.apache.org/jira/browse/CAMEL-14874>, I’ve opened a bunch of follow-on issues, some of which I will work on if they seem like a good idea.
> >
> > The first two I don’t expect to work on, unless the solution to the 2nd is to disable the extensions causing the problem.
> >
> > CAMEL-14904 <https://issues.apache.org/jira/browse/CAMEL-14904> Nav pane does not show current page
> >
> > CAMEL-14905 <https://issues.apache.org/jira/browse/CAMEL-14905> "responsive" table settings make it impossible to set reasonable column sizes.
> >
> > The next three I’m happy to work on.
> > CAMEL-14906 <https://issues.apache.org/jira/browse/CAMEL-14906> user manual index page should not list entire contents of another component.
> > CAMEL-14907 <https://issues.apache.org/jira/browse/CAMEL-14907> Consider separating core and non-core components in the components index page
> >
> > CAMEL-14908 <https://issues.apache.org/jira/browse/CAMEL-14908> Consider generating component index tables with Antora in 3.2.x branch and possibly 2.x branch.
> >
> > The last two require some discussion before proceeding.
> >
> > CAMEL-14909 <https://issues.apache.org/jira/browse/CAMEL-14909> Decide what to do with bindy component(s) doc page(s)
> >
> > CAMEL-14910 <https://issues.apache.org/jira/browse/CAMEL-14910> Decide if component summary pages are a good idea
> >
> > There’s also
> > CAMEL-14866 <https://issues.apache.org/jira/browse/CAMEL-14866> camel website - Show on component table the supportLevel
> > The support level is now shown in text, combined with the deprecated state. If someone comes up with icons I can use them or indicate how to use them.
> >
> > thanks
> > David Jencks
> >
> >
> >> On Apr 14, 2020, at 2:50 PM, David Jencks <david.a.jencks@gmail.com <ma...@gmail.com>> wrote:
> >>
> >> I think this stage of this work is done, I’ve opened PRs for the 5 repo/branches involved.
> >>
> >> There’s a preview at https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html <https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html> of the Antora part of the site. I haven’t been able to build the hugo part for quite a while, but don’t have any interest in investigating why.
> >>
> >> My build turns off the responsive table extensions, as they mangle the table layout and make it almost unreadable. My PR doesn’t do this however.
> >>
> >> Current state of the things mentioned below:
> >>
> >> - support level includes text combining plain support level and deprecation.
> >>
> >> - There’s only one link to the bindy data formats. I can think of lots of other possibilities but lets work that out later.
> >>
> >> - After looking at all the mystery pages I decided that they are actually useful summaries of collections of components. They now appear in the nav list at the head of the things they summarize and in the index table above the things they summarize. (the spring-main page is actually a poorly documented component, now appropriately classified).
> >>
> >>
> >> I changed the adoc processing in UpdateReadmeMojo quite a bit:
> >> - It now generates all the header information in one go.
> >> - It makes no attempt however feeble to lint the adoc.
> >> - It makes no attempt to second guess the nature of some required strings, but fails the build immediately if they aren’t present. The previous code was missing all sorts of problems, which I cleaned up by hand. The required strings are:
> >>
> >> For all component-like files:
> >> *Since Camel {since}*
> >>
> >> For components:
> >>
> >> *{component-header}*
> >>
> >> One comment inline….
> >>
> >> Thanks
> >> David Jencks
> >>
> >>> On Apr 14, 2020, at 12:34 AM, Claus Ibsen <claus.ibsen@gmail.com <ma...@gmail.com>> wrote:
> >>>
> >>> On Fri, Apr 10, 2020 at 6:31 PM David Jencks <david.a.jencks@gmail.com <ma...@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’m not a graphic designer, but I assume that the icons would combine a color and letter or symbol. If the “stable" icon was say an S on a gold background, the “deprecated” could be a paler S on a grey background.
> >>
> >>>
> >>>> 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> <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> <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> <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> <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> <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> <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.ibsen@gmail.com <ma...@gmail.com>> wrote:
> >>>>>
> >>>>> On Fri, Apr 10, 2020 at 7:58 AM David Jencks <david.a.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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>> <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><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> <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><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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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 <ancosen@gmail.com <ma...@gmail.com> <mailto:ancosen@gmail.com <ma...@gmail.com>> <mailto:ancosen@gmail.com <ma...@gmail.com><mailto:ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@gmail.com> <mailto:claus.ibsen@gmail.com <ma...@gmail.com>> <mailto:claus.ibsen@gmail.com <ma...@gmail.com><mailto:claus.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@regvart.com> <mailto:zoran@regvart.com <ma...@regvart.com>> <mailto:zoran@regvart.com <ma...@regvart.com><mailto:zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@gmail.com>> <mailto:david.a.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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><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 <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 <http://davsclaus.com/> @davsclaus
> >>>>>>>>> Camel in Action 2: https://www.manning.com/ibsen2 <https://www.manning.com/ibsen2>
> >>>>>>>>>
> >>>>>>>
> >>>>>>
> >>>>>
> >>>>>
> >>>>> --
> >>>>> Claus Ibsen
> >>>>> -----------------
> >>>>> http://davsclaus.com <http://davsclaus.com/> <http://davsclaus.com/ <http://davsclaus.com/>> @davsclaus
> >>>>> Camel in Action 2: https://www.manning.com/ibsen2 <https://www.manning.com/ibsen2> <https://www.manning.com/ibsen2 <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
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by David Jencks <da...@gmail.com>.
I’ve supplied PRs for CAMEL-14906 <https://issues.apache.org/jira/browse/CAMEL-14906> and CAMEL-14907 <https://issues.apache.org/jira/browse/CAMEL-14907>.
I put up a preview showing both these changes:
https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html#_components_data_formats_languages_and_enterprise_integration_patterns
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>
Are these improvements?
Somehow the component counts disappeared from the previous commits, so if 14907 is rejected they’ll need to be added back.
Thanks
David Jencks
> On Apr 14, 2020, at 9:21 PM, David Jencks <da...@gmail.com> wrote:
>
> Having closed the issue for this, CAMEL-14874 <https://issues.apache.org/jira/browse/CAMEL-14874>, I’ve opened a bunch of follow-on issues, some of which I will work on if they seem like a good idea.
>
> The first two I don’t expect to work on, unless the solution to the 2nd is to disable the extensions causing the problem.
>
> CAMEL-14904 <https://issues.apache.org/jira/browse/CAMEL-14904> Nav pane does not show current page
>
> CAMEL-14905 <https://issues.apache.org/jira/browse/CAMEL-14905> "responsive" table settings make it impossible to set reasonable column sizes.
>
> The next three I’m happy to work on.
> CAMEL-14906 <https://issues.apache.org/jira/browse/CAMEL-14906> user manual index page should not list entire contents of another component.
> CAMEL-14907 <https://issues.apache.org/jira/browse/CAMEL-14907> Consider separating core and non-core components in the components index page
>
> CAMEL-14908 <https://issues.apache.org/jira/browse/CAMEL-14908> Consider generating component index tables with Antora in 3.2.x branch and possibly 2.x branch.
>
> The last two require some discussion before proceeding.
>
> CAMEL-14909 <https://issues.apache.org/jira/browse/CAMEL-14909> Decide what to do with bindy component(s) doc page(s)
>
> CAMEL-14910 <https://issues.apache.org/jira/browse/CAMEL-14910> Decide if component summary pages are a good idea
>
> There’s also
> CAMEL-14866 <https://issues.apache.org/jira/browse/CAMEL-14866> camel website - Show on component table the supportLevel
> The support level is now shown in text, combined with the deprecated state. If someone comes up with icons I can use them or indicate how to use them.
>
> thanks
> David Jencks
>
>
>> On Apr 14, 2020, at 2:50 PM, David Jencks <david.a.jencks@gmail.com <ma...@gmail.com>> wrote:
>>
>> I think this stage of this work is done, I’ve opened PRs for the 5 repo/branches involved.
>>
>> There’s a preview at https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html <https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html> of the Antora part of the site. I haven’t been able to build the hugo part for quite a while, but don’t have any interest in investigating why.
>>
>> My build turns off the responsive table extensions, as they mangle the table layout and make it almost unreadable. My PR doesn’t do this however.
>>
>> Current state of the things mentioned below:
>>
>> - support level includes text combining plain support level and deprecation.
>>
>> - There’s only one link to the bindy data formats. I can think of lots of other possibilities but lets work that out later.
>>
>> - After looking at all the mystery pages I decided that they are actually useful summaries of collections of components. They now appear in the nav list at the head of the things they summarize and in the index table above the things they summarize. (the spring-main page is actually a poorly documented component, now appropriately classified).
>>
>>
>> I changed the adoc processing in UpdateReadmeMojo quite a bit:
>> - It now generates all the header information in one go.
>> - It makes no attempt however feeble to lint the adoc.
>> - It makes no attempt to second guess the nature of some required strings, but fails the build immediately if they aren’t present. The previous code was missing all sorts of problems, which I cleaned up by hand. The required strings are:
>>
>> For all component-like files:
>> *Since Camel {since}*
>>
>> For components:
>>
>> *{component-header}*
>>
>> One comment inline….
>>
>> Thanks
>> David Jencks
>>
>>> On Apr 14, 2020, at 12:34 AM, Claus Ibsen <claus.ibsen@gmail.com <ma...@gmail.com>> wrote:
>>>
>>> On Fri, Apr 10, 2020 at 6:31 PM David Jencks <david.a.jencks@gmail.com <ma...@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’m not a graphic designer, but I assume that the icons would combine a color and letter or symbol. If the “stable" icon was say an S on a gold background, the “deprecated” could be a paler S on a grey background.
>>
>>>
>>>> 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> <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> <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> <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> <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> <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> <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.ibsen@gmail.com <ma...@gmail.com>> wrote:
>>>>>
>>>>> On Fri, Apr 10, 2020 at 7:58 AM David Jencks <david.a.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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>> <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><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> <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><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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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 <ancosen@gmail.com <ma...@gmail.com> <mailto:ancosen@gmail.com <ma...@gmail.com>> <mailto:ancosen@gmail.com <ma...@gmail.com><mailto:ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@gmail.com> <mailto:claus.ibsen@gmail.com <ma...@gmail.com>> <mailto:claus.ibsen@gmail.com <ma...@gmail.com><mailto:claus.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@regvart.com> <mailto:zoran@regvart.com <ma...@regvart.com>> <mailto:zoran@regvart.com <ma...@regvart.com><mailto:zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@gmail.com>> <mailto:david.a.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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><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 <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 <http://davsclaus.com/> @davsclaus
>>>>>>>>> Camel in Action 2: https://www.manning.com/ibsen2 <https://www.manning.com/ibsen2>
>>>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Claus Ibsen
>>>>> -----------------
>>>>> http://davsclaus.com <http://davsclaus.com/> <http://davsclaus.com/ <http://davsclaus.com/>> @davsclaus
>>>>> Camel in Action 2: https://www.manning.com/ibsen2 <https://www.manning.com/ibsen2> <https://www.manning.com/ibsen2 <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>
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by David Jencks <da...@gmail.com>.
Having closed the issue for this, CAMEL-14874 <https://issues.apache.org/jira/browse/CAMEL-14874>, I’ve opened a bunch of follow-on issues, some of which I will work on if they seem like a good idea.
The first two I don’t expect to work on, unless the solution to the 2nd is to disable the extensions causing the problem.
CAMEL-14904 <https://issues.apache.org/jira/browse/CAMEL-14904> Nav pane does not show current page
CAMEL-14905 <https://issues.apache.org/jira/browse/CAMEL-14905> "responsive" table settings make it impossible to set reasonable column sizes.
The next three I’m happy to work on.
CAMEL-14906 <https://issues.apache.org/jira/browse/CAMEL-14906> user manual index page should not list entire contents of another component.
CAMEL-14907 <https://issues.apache.org/jira/browse/CAMEL-14907> Consider separating core and non-core components in the components index page
CAMEL-14908 <https://issues.apache.org/jira/browse/CAMEL-14908> Consider generating component index tables with Antora in 3.2.x branch and possibly 2.x branch.
The last two require some discussion before proceeding.
CAMEL-14909 <https://issues.apache.org/jira/browse/CAMEL-14909> Decide what to do with bindy component(s) doc page(s)
CAMEL-14910 <https://issues.apache.org/jira/browse/CAMEL-14910> Decide if component summary pages are a good idea
There’s also
CAMEL-14866 <https://issues.apache.org/jira/browse/CAMEL-14866> camel website - Show on component table the supportLevel
The support level is now shown in text, combined with the deprecated state. If someone comes up with icons I can use them or indicate how to use them.
thanks
David Jencks
> On Apr 14, 2020, at 2:50 PM, David Jencks <da...@gmail.com> wrote:
>
> I think this stage of this work is done, I’ve opened PRs for the 5 repo/branches involved.
>
> There’s a preview at https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html <https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html> of the Antora part of the site. I haven’t been able to build the hugo part for quite a while, but don’t have any interest in investigating why.
>
> My build turns off the responsive table extensions, as they mangle the table layout and make it almost unreadable. My PR doesn’t do this however.
>
> Current state of the things mentioned below:
>
> - support level includes text combining plain support level and deprecation.
>
> - There’s only one link to the bindy data formats. I can think of lots of other possibilities but lets work that out later.
>
> - After looking at all the mystery pages I decided that they are actually useful summaries of collections of components. They now appear in the nav list at the head of the things they summarize and in the index table above the things they summarize. (the spring-main page is actually a poorly documented component, now appropriately classified).
>
>
> I changed the adoc processing in UpdateReadmeMojo quite a bit:
> - It now generates all the header information in one go.
> - It makes no attempt however feeble to lint the adoc.
> - It makes no attempt to second guess the nature of some required strings, but fails the build immediately if they aren’t present. The previous code was missing all sorts of problems, which I cleaned up by hand. The required strings are:
>
> For all component-like files:
> *Since Camel {since}*
>
> For components:
>
> *{component-header}*
>
> One comment inline….
>
> Thanks
> David Jencks
>
>> On Apr 14, 2020, at 12:34 AM, Claus Ibsen <claus.ibsen@gmail.com <ma...@gmail.com>> wrote:
>>
>> On Fri, Apr 10, 2020 at 6:31 PM David Jencks <david.a.jencks@gmail.com <ma...@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’m not a graphic designer, but I assume that the icons would combine a color and letter or symbol. If the “stable" icon was say an S on a gold background, the “deprecated” could be a paler S on a grey background.
>
>>
>>> 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> <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> <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> <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> <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> <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> <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.ibsen@gmail.com <ma...@gmail.com>> wrote:
>>>>
>>>> On Fri, Apr 10, 2020 at 7:58 AM David Jencks <david.a.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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>> <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><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> <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><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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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 <ancosen@gmail.com <ma...@gmail.com> <mailto:ancosen@gmail.com <ma...@gmail.com>> <mailto:ancosen@gmail.com <ma...@gmail.com><mailto:ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@gmail.com> <mailto:claus.ibsen@gmail.com <ma...@gmail.com>> <mailto:claus.ibsen@gmail.com <ma...@gmail.com><mailto:claus.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@regvart.com> <mailto:zoran@regvart.com <ma...@regvart.com>> <mailto:zoran@regvart.com <ma...@regvart.com><mailto:zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@gmail.com>> <mailto:david.a.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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><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/> <http://davsclaus.com/ <http://davsclaus.com/>> @davsclaus
>>>> Camel in Action 2: https://www.manning.com/ibsen2 <https://www.manning.com/ibsen2> <https://www.manning.com/ibsen2 <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>
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by David Jencks <da...@gmail.com>.
I think this stage of this work is done, I’ve opened PRs for the 5 repo/branches involved.
There’s a preview at https://camel-preview-1.s3-us-west-2.amazonaws.com/manual/latest/index.html of the Antora part of the site. I haven’t been able to build the hugo part for quite a while, but don’t have any interest in investigating why.
My build turns off the responsive table extensions, as they mangle the table layout and make it almost unreadable. My PR doesn’t do this however.
Current state of the things mentioned below:
- support level includes text combining plain support level and deprecation.
- There’s only one link to the bindy data formats. I can think of lots of other possibilities but lets work that out later.
- After looking at all the mystery pages I decided that they are actually useful summaries of collections of components. They now appear in the nav list at the head of the things they summarize and in the index table above the things they summarize. (the spring-main page is actually a poorly documented component, now appropriately classified).
I changed the adoc processing in UpdateReadmeMojo quite a bit:
- It now generates all the header information in one go.
- It makes no attempt however feeble to lint the adoc.
- It makes no attempt to second guess the nature of some required strings, but fails the build immediately if they aren’t present. The previous code was missing all sorts of problems, which I cleaned up by hand. The required strings are:
For all component-like files:
*Since Camel {since}*
For components:
*{component-header}*
One comment inline….
Thanks
David Jencks
> On Apr 14, 2020, at 12:34 AM, Claus Ibsen <cl...@gmail.com> wrote:
>
> On Fri, Apr 10, 2020 at 6:31 PM David Jencks <david.a.jencks@gmail.com <ma...@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’m not a graphic designer, but I assume that the icons would combine a color and letter or symbol. If the “stable" icon was say an S on a gold background, the “deprecated” could be a paler S on a grey background.
>
>> 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> <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> <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> <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> <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> <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> <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.ibsen@gmail.com <ma...@gmail.com>> wrote:
>>>
>>> On Fri, Apr 10, 2020 at 7:58 AM David Jencks <david.a.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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>> <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><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> <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><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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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 <ancosen@gmail.com <ma...@gmail.com> <mailto:ancosen@gmail.com <ma...@gmail.com>> <mailto:ancosen@gmail.com <ma...@gmail.com><mailto:ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@gmail.com> <mailto:claus.ibsen@gmail.com <ma...@gmail.com>> <mailto:claus.ibsen@gmail.com <ma...@gmail.com><mailto:claus.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@regvart.com> <mailto:zoran@regvart.com <ma...@regvart.com>> <mailto:zoran@regvart.com <ma...@regvart.com><mailto:zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@gmail.com>> <mailto:david.a.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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><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/> <http://davsclaus.com/ <http://davsclaus.com/>> @davsclaus
>>> Camel in Action 2: https://www.manning.com/ibsen2 <https://www.manning.com/ibsen2> <https://www.manning.com/ibsen2 <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>
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by Claus Ibsen <cl...@gmail.com>.
On Fri, Apr 10, 2020 at 6:31 PM David Jencks <da...@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 <cl...@gmail.com> wrote:
> >
> > On Fri, Apr 10, 2020 at 7:58 AM David Jencks <david.a.jencks@gmail.com <ma...@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.jencks@gmail.com <ma...@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 <ancosen@gmail.com <ma...@gmail.com> <mailto:ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@gmail.com> <mailto:claus.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@regvart.com> <mailto:zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by David Jencks <da...@gmail.com>.
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 <da...@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.ibsen@gmail.com <ma...@gmail.com>> wrote:
>>
>> On Fri, Apr 10, 2020 at 7:58 AM David Jencks <david.a.jencks@gmail.com <ma...@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.jencks@gmail.com <ma...@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 <ancosen@gmail.com <ma...@gmail.com> <mailto:ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@gmail.com> <mailto:claus.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@regvart.com> <mailto:zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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>
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by David Jencks <da...@gmail.com>.
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 <cl...@gmail.com> wrote:
>
> On Fri, Apr 10, 2020 at 7:58 AM David Jencks <david.a.jencks@gmail.com <ma...@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.jencks@gmail.com <ma...@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 <ancosen@gmail.com <ma...@gmail.com> <mailto:ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@gmail.com> <mailto:claus.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@regvart.com> <mailto:zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@gmail.com> <mailto:david.a.jencks@gmail.com <ma...@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>
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by Claus Ibsen <cl...@gmail.com>.
On Fri, Apr 10, 2020 at 7:58 AM David Jencks <da...@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> (the new page).
>
> The source is in branches named issue-14874-generate-index-tables in https://github.com/djencks/camel-website.git and 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
> 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 <da...@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 <ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@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
> >>>>
> >>>>>
> >>>>> 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 @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by David Jencks <da...@gmail.com>.
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> (the new page).
The source is in branches named issue-14874-generate-index-tables in https://github.com/djencks/camel-website.git and 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.
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.
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.
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 <da...@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 <ancosen@gmail.com <ma...@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.ibsen@gmail.com <ma...@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 <zoran@regvart.com <ma...@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.jencks@gmail.com <ma...@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
>>>>
>>>>>
>>>>> 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
>>>
>
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by David Jencks <da...@gmail.com>.
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 <an...@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 <cl...@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 <da...@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
>>
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by Andrea Cosentino <an...@gmail.com>.
Maybe we can also review the labels a bit and reducing the number
Il mar 7 apr 2020, 11:40 Claus Ibsen <cl...@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 <da...@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
>
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by Claus Ibsen <cl...@gmail.com>.
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 <da...@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
Re: [Website] Possibility to generate component, data format,
languages index tables
Posted by Zoran Regvart <zo...@regvart.com>.
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 <da...@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