I’ve addressed all the problems I know about…. now we can find more :-)
At this point I think we could apply the PRs and work from there. In more detail: (1) https://github.com/apache/camel-kamelets/pull/487 fixes the Kamelet catalog rendering and AFAICT doesn’t break the Antora 2 build. I’d merge this but I’m not sure I know all the places to look for problems :-) (2) [website] Issue 16854 antora 3 <https://github.com/apache/camel-website/pull/617> Preview at https://pr-617--camel.netlify.app <https://pr-617--camel.netlify.app/>. This uses a camel-website setup with the latest Antora 3.0.0-alpha.9 ready to build the next set of changes: the preview is against the current content state. The only problem I know of is the Kamelet catalog which would be fixed by the preceding PR. (3) [Website] Use @djencks/asciidoctor-jsonpath to generate component doc content <https://github.com/apache/camel/pull/6040>. Preview at https://pr-614--camel.netlify.app <https://pr-614--camel.netlify.app/> (with the Kamelet catalog fix) (using a customized playbook). (3) should be rebased on main and the generated changes regenerated just before merging. Issues (all with (2)): - I’ve committed the results of running yarn in antora-ui-camel and root, but I’m not at all sure this is correct. The build seems to work in CI, but I’m on MacOS. In particular I sometimes seem to end up with a 50Mb+ file for the UI that I don’t see in the current state. - Using yarn workspaces topology/dependency detection to build the UI first doesn’t work for me, locally or in CI. I’ve hard-coded building the UI first. I think this is more reliable so a good idea, but perhaps I did something wrong. - I removed patch-sitemap.js usage. I can’t tell what it’s supposed to be doing or why and, even if it’s needed, it should be implemented as a pipeline extension. AFAIK Zoran put all these in place so perhaps we need his input. Comments: - I think that the EIP doc pages haven’t been updated for some time: the UpdateReadmeMojo appeared to be looking in the wrong directory. Certainly the previous version of my work wasn’t using the jsonpath eip template I wrote. - The first row of generated tables is now treated the same as following rows: this fixes the enum list display in descriptions and the bold name problem. - I think I’ve excluded the same rows from all tables as the preceding approach. - The main options tables for all kinds have the same columns but not always in the same order. Perhaps we should make the order the same? components: activemq-component.html <https://pr-614--camel.netlify.app/components/latest/activemq-component.html#_component_options> | Name | Description | Default | Type dataformats: any23-dataformat.html <https://pr-614--camel.netlify.app/components/latest/dataformats/any23-dataformat.html#_any23_options> | Name | Default | Java Type | Description languages: bean-language.html <https://pr-614--camel.netlify.app/components/latest/languages/bean-language.html#_bean_language_options> | Name | Default | Java Type | Description eips: aggregate-eip.html <https://pr-614--camel.netlify.app/components/latest/eips/aggregate-eip.html#_aggregator_options> | Name | Description | Default | Type We’re always showing the java type short name, so we should also decide between Type and Java Type. - UpdateReadmeMojo can be further simplified, and I may get to it shortly, but that can also be done later. - docs/gulpfile.js can be (IMO) considerably simplified by driving more of the symlink generation from data: I already did this for the new json symlinks. The disadvantage is that the task is then anonymous so you can’t tell what gulp is doing as easily. - I think I’m creating a lot of unused json symlinks for at least dataformats and eips because I can’t figure out how to find only the relevant ones. We should probably deal with this later. - There are some inconsistencies in naming and directory layout for some components that we should probably deal with later if at all. David Jencks > On Sep 3, 2021, at 1:46 AM, Claus Ibsen <claus.ib...@gmail.com> wrote: > > Hi > > Great work David. > > I noticed the data formats table, then the 1st row is in bold, and the > others are not, and the styling of the javaType is also different > https://pr-614--camel.netlify.app/components/latest/dataformats/thrift-dataformat.html > > <https://pr-614--camel.netlify.app/components/latest/dataformats/thrift-dataformat.html> > > And for languages then we should skip the "expression" row as its not > really an option but the actual language code being used (implied). > https://pr-614--camel.netlify.app/components/latest/languages/jsonpath-language.html > > <https://pr-614--camel.netlify.app/components/latest/languages/jsonpath-language.html> > > You can compare these pages with the regular website to see the subtle > differences. > > > For EIP patterns then maybe we should style the Type column to be same > as for the others (blue color, lower case for boolean, string, int > etc.) > https://pr-614--camel.netlify.app/components/latest/eips/claimCheck-eip.html > <https://pr-614--camel.netlify.app/components/latest/eips/claimCheck-eip.html> > > > On Fri, Sep 3, 2021 at 8:21 AM David Jencks <david.a.jen...@gmail.com > <mailto:david.a.jen...@gmail.com>> wrote: >> >> I think this work is complete enough to be used. There’s now a Ci built >> preview at https://pr-614--camel.netlify.app >> >> The main work is on https://github.com/apache/camel/pull/6040. Possibly the >> commits should be squashed into fewer. Once this is merged the >> camel-website PR can be updated to use the normal repos/branches. >> >> Subsidiary PRs fixing warnings that would now break the build: (these can be >> merged before the main work) >> >> https://github.com/apache/camel-kamelets/pull/480 (no error from Antora). >> This is the bizarre looking Kamelets catalog page fix. I have no idea why >> the previous adoc worked, but this works on both Antora 2 and 3 >> >> https://github.com/apache/camel-quarkus/pull/3064 >> https://github.com/apache/camel-quarkus/pull/3065 >> >> https://github.com/apache/camel/pull/6039 >> >> comments: >> >> - I removed the patch-sitemap.js use. I can’t figure out why this is >> needed. If it really is needed, it should be done with a pipeline extension. >> - yarn workspace —topological-dev is not building the UI before it’s used. >> I can’t figure out why; it is for other PRs. I replaced this by just >> calling the UI build directly. >> - If nothing else is using the model building in UpdateReadmeMojo it can >> probably be simplified further. >> - The camel-website node dependencies have changed dramatically. It looks >> like the yarn cache is checked into git; I haven’t checked in the changes. >> Should I? >> >> known problems: >> >> - When the first row contains a description with a list, the list isn’t >> rendered properly. cf. >> https://pr-614--camel.netlify.app/components/latest/activemq-component.html#_path_parameters_2_parameters >> >> <https://pr-614--camel.netlify.app/components/latest/activemq-component.html#_path_parameters_2_parameters> >> >> <https://pr-614--camel.netlify.app/components/latest/activemq-component.html#_path_parameters_2_parameters >> >> <https://pr-614--camel.netlify.app/components/latest/activemq-component.html#_path_parameters_2_parameters>> >> - All the names in the generated tables have ids so they can be linked to >> but there’s no easy way to find out the id. The sections have a link to >> themselves which makes it easy to copy the URL. I haven’t looked into >> whether this can be done with the table entries. >> >> Updating the main PR to track changes in camel is somewhat time consuming so >> I’d appreciate it if we could move this towards resolution quickly. >> >> David Jencks >> >> >>> On Aug 31, 2021, at 11:42 PM, David Jencks <david.a.jen...@gmail.com >>> <mailto:david.a.jen...@gmail.com>> wrote: >>> >>> With both the CI build for my PR and locally, `yarn build-all` is building >>> the UI after the main build command. Obviously this doesn’t work. >>> >>> Can someone point to a situation in which the UI is built before it is >>> used? Any ideas why yarn is picking this dysfunctional workspace build >>> order? >>> >>> David Jencks >>> >>>> On Aug 30, 2021, at 1:23 AM, Claus Ibsen <claus.ib...@gmail.com >>>> <mailto:claus.ib...@gmail.com> <mailto:claus.ib...@gmail.com >>>> <mailto:claus.ib...@gmail.com>>> wrote: >>>> >>>> On Sun, Aug 29, 2021 at 10:20 AM David Jencks <david.a.jen...@gmail.com >>>> <mailto:david.a.jen...@gmail.com> <mailto:david.a.jen...@gmail.com >>>> <mailto:david.a.jen...@gmail.com>>> wrote: >>>>> >>>>> The current source state is now visible. >>>>> >>>>> - I npm-published my asciidoctor-jsonpath extension >>>>> - The site content changes are at https://github.com/djencks/camel.git >>>>> <https://github.com/djencks/camel.git> >>>>> <https://github.com/djencks/camel.git >>>>> <https://github.com/djencks/camel.git>> jsonpath-options branch. I’ve put >>>>> all the generated changes as the last commit, so it should be possible to >>>>> update the branch by dropping the last commit, rebasing on main, and >>>>> regenerating the source with the maven build. >>>>> - The camel-website changes are at >>>>> 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>> >>>>> issue-16854-jsonpath-options branch >>>>> >>>>> There’s a PR https://github.com/apache/camel-website/pull/614 >>>>> <https://github.com/apache/camel-website/pull/614> >>>>> <https://github.com/apache/camel-website/pull/614 >>>>> <https://github.com/apache/camel-website/pull/614>>. >>>>> >>>>> I don’t understand what the patch-sitemap.js does and was having >>>>> dependency problems so removed it from the command line. What does it do >>>>> and why? >>>>> >>>>> The PR’s build fails because of missing ui bundle. Is this expected? I >>>>> like to have the built UI bundle available somewhere: I often check in >>>>> the built bundle. Locally I can’t build the UI, it complains somehow >>>>> about the helpers for component sorting/hiding. >>>>> >>>>> I set up the build to fail on warnings, and there are quite a few >>>>> warnings. >>>>> >>>>> There are several source problems I don’t know the proper fix for as it >>>>> requires domain knowledge. One is these warnings: >>>>> >>>>> [00:47:14.821] WARN (asciidoctor): skipping reference to missing >>>>> attribute: apisyntax >>>>> file: >>>>> docs/components/modules/ROOT/pages/google-calendar-stream-component.adoc >>>>> source: https://github.com/djencks/camel.git >>>>> <https://github.com/djencks/camel.git> >>>>> <https://github.com/djencks/camel.git >>>>> <https://github.com/djencks/camel.git>> (refname: jsonpath-options, start >>>>> path: docs/components) >>>>> [00:47:15.979] WARN (asciidoctor): skipping reference to missing >>>>> attribute: apisyntax >>>>> file: >>>>> docs/components/modules/ROOT/pages/google-mail-stream-component.adoc >>>>> source: https://github.com/djencks/camel.git >>>>> <https://github.com/djencks/camel.git> >>>>> <https://github.com/djencks/camel.git >>>>> <https://github.com/djencks/camel.git>> (refname: jsonpath-options, start >>>>> path: docs/components) >>>>> [00:47:16.442] WARN (asciidoctor): skipping reference to missing >>>>> attribute: apisyntax >>>>> file: >>>>> docs/components/modules/ROOT/pages/google-sheets-stream-component.adoc >>>>> source: https://github.com/djencks/camel.git >>>>> <https://github.com/djencks/camel.git> >>>>> <https://github.com/djencks/camel.git >>>>> <https://github.com/djencks/camel.git>> (refname: jsonpath-options, start >>>>> path: docs/components) >>>>> >>>>> >>>>> These three components are missing an apisyntax entry in their json >>>>> files. The problem shows up in the current site as the literal string >>>>> ’null’. >>>>> >>>> >>>> Ah yeah it looks like the -stream components are not API based, I am >>>> going to fix this for Camel 3.12. >>>> >>>> >>>>> There are some inconsistencies and mysteries in the gulpfile.js. I’ve >>>>> commented on some. >>>>> >>>>> It would be great to know if anyone else can build the site from the PR >>>>> branch. >>>>> >>>>> David Jencks >>>>> >>>>>> On Aug 23, 2021, at 6:00 AM, Claus Ibsen <claus.ib...@gmail.com >>>>>> <mailto:claus.ib...@gmail.com> <mailto:claus.ib...@gmail.com >>>>>> <mailto:claus.ib...@gmail.com>>> wrote: >>>>>> >>>>>> Hi >>>>>> >>>>>> Ah yeah those were an idea to include the full page documentation in >>>>>> case tooling may be able to use that for something useable. >>>>>> However the tooling uses all the other bits, so we have just marked >>>>>> those apis as deprecated. >>>>>> >>>>>> So we can remove the files from the camel-catalog. >>>>>> I have created a ticket to remove them >>>>>> https://issues.apache.org/jira/browse/CAMEL-16881 >>>>>> <https://issues.apache.org/jira/browse/CAMEL-16881> >>>>>> <https://issues.apache.org/jira/browse/CAMEL-16881 >>>>>> <https://issues.apache.org/jira/browse/CAMEL-16881>> >>>>>> >>>>>> On Sun, Aug 22, 2021 at 9:48 AM Zoran Regvart <zo...@regvart.com >>>>>> <mailto:zo...@regvart.com>> wrote: >>>>>>> >>>>>>> Hi David, >>>>>>> >>>>>>> On Sat, Aug 21, 2021 at 10:10 PM David Jencks <david.a.jen...@gmail.com >>>>>>> <mailto:david.a.jen...@gmail.com>> wrote: >>>>>>>> >>>>>>>> I have a question about the purpose of the .adoc files in the catalog. >>>>>>>> The changes proposed here will remove the tables of options from >>>>>>>> these copies of the component .adoc files. These copies are already >>>>>>>> quite skimpy as they don’t successfully include the spring-boot >>>>>>>> information. >>>>>>>> >>>>>>>> What are these copies of the .adoc files supposed to be useful for? >>>>>>> >>>>>>> I think the catalog contains those so that an alternative UI can show >>>>>>> them, think tooltips or inline help in an IDE. I think, though I'm not >>>>>>> 100% sure that VSCode tooling is using that... >>>>>>> >>>>>>>> If there’s a desire to make them more complete, one strategy would be >>>>>>>> to build the components module of the website using a custom UI that >>>>>>>> has nothing in it, so we just get plain undecorated html pages, and >>>>>>>> putting those in the catalog. It would require some investigation, >>>>>>>> but it might conceivably be possible to arrange so links out of the >>>>>>>> components module go to the website rather than just be broken. >>>>>>> >>>>>>> I'd keep it as simple as it can be, so plain .adoc files, or if we >>>>>>> find out they're not used just remove them... >>>>>>> >>>>>>> 2c >>>>>>> >>>>>>> zoran >>>>>>> -- >>>>>>> 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>
