Re: [Website] Possible change in components page generation (preview available)
Hi Zoran, > On Aug 17, 2021, at 2:46 AM, Zoran Regvart wrote: > > Hi David > > On Tue, Aug 17, 2021 at 7:42 AM David Jencks wrote: >> >> I’ve made a lot of progress on this and put up a preview of the current >> state. Only components in the latest branch are done (not dataformats, eips, >> languages, other, and not other versions). > > Perhaps we can create (sub)issues for outstanding work so folk can > jump in and help as well? The others look easy :-) but finding out if anyone else can configure the extension might be useful:-) I don’t want to push the plugin code until I’ve reviewed and documented it, and likely I’ll spend a few minutes doing the others before I get done with those tasks. We’ll see. > >> The arrangement of, in particular, API data didn’t make much sense to me so >> I reorganized it so relevant information is all together, and added a lot of >> in-page links. > > What sometimes bothered me is that I could not point someone to an > exact option in the table, perhaps this is for another time but I > think it would be good to have much more anchors within the page, one > of those would be for each individual option. Perhaps as a follow up > on this work. This is easy to do :-), it should be in the next preview. Perhaps because they are links into a table, Asciidoctor doesn’t seem to get them into the anchor catalog and can’t verify that the links are valid, so there are info messages. However, the links appear to work fine. Info messages would only occur for in-page links, which are somewhat unlikely. > >> There are a couple of glitches… >> - “debugging code” showing e.g. "pascalcasescheme: Twilio” > > I'd assume this would be trivial to fix :) :-) > >> - For some reason lists don’t display properly in the first row of tables. >> At >> https://camel-preview-1.s3.us-west-2.amazonaws.com/components/latest/twilio-component.html#_path_parameters_2_parameters >> compare the apiName row and the methodName row. >> >> https://camel-preview-1.s3.us-west-2.amazonaws.com/components/latest/twilio-component.html >> is the most complex page, and can be compared to the current site at >> https://camel.apache.org/components/latest/twilio-component.html. > > Yeah, we could also add the enum values inline, i.e. not in a list, > perhaps within a tag, not sure if it's worth spending too much > of an effort on this. I'd create a follow up issue for this and any > other cleanup tasks... I really like the list as opposed to listing the values in a sentence. It might be a bug in asciidoctor or in my extension. In any case I don’t think it’s a blocker. > >> I haven’t published the updates needed to the Asciidoctor extension that >> does the generation, so a PR is not yet feasible. > > Would love to see how this is shaping up, even if you have it > somewhere in a draft phase it would be good to get familiar with the > code. Perhaps we can create a branch on the camel-website and work on > it from there? Would be easy (I think) to set up a preview via GitHub > Workflow + Netlify or a Jenkins build and a staging site hosted by > ASF... I think this is probably feasible once I push my changes to my jsonpath Asciidoctor extension to gitlab, but I’m not quite ready to do that. I could push the camel changes to a branch before that, but it wouldn’t be buildable. > > I've noticed that the Kamelet catalog is not rendering correctly > (https://camel-preview-1.s3.us-west-2.amazonaws.com/camel-kamelets/latest/index.html), > not sure if that's a CSS issue or it has something to do with the > changes you're making. I’m not sure what’s going on with that! It looks quite amazingly out of proportion!! I tried updating the ui and rebuilding and got worse problems with the custom component ordering blowing up, and I haven’t been able to get anything to work with yarn. Before worrying about the Kamelet catalog lets get this in a state others can build. I doubt it’s anything I did, I think it’s a problem of some sort with my copy of the camel UI. > > Thanks David for taking this on, looking forward to this, it should > cut down a lot of the complexity in how we build the website and > remove some of the work needed in the main camel repository. I can > even see us not needing to do as many regen commits as an outcome of > this! Yes, I think the only function of the UpdateReadmeMojo is going to be to set the header attributes. We’ll see. This does involve a lot of manipulation of javascript objects, and it may well slow the website build down a bit. I implemented some caching so each .json file is only read once per page, so I don’t think it’s likely to make the build unusably slow. > > zoran > -- > Zoran Regvart David Jencks
Re: [Website] Better error checking
Hi Oh that is great to see more detailed WARN / ERROR as today we get too limited information so its almost a needle in the haystack where the problem really is. And you have to hunt across the sub projects and their docs as well to find it. At least the file name as above will be a great pointer to find the problem. On Tue, Aug 17, 2021 at 7:53 AM David Jencks wrote: > > Related to my proposal to change how component pages are (partially) > generated I expect to be proposing to move to the latest Antora 3 alpha. In > particular this has logging and the ability to be configured to fail on log > levels, in particular warnings. This will make the xref-checker obsolete, as > logging provides more detailed information. > > Currently the warnings and errors from the build are: > > [22:44:07.521] WARN (asciidoctor): skipping reference to missing attribute: > myclient > file: docs/user-manual/modules/ROOT/pages/route-template.adoc > source: https://github.com/apache/camel.git (refname: main, start path: > docs/user-manual) > [22:44:07.524] WARN (asciidoctor): skipping reference to missing attribute: > myclient > file: docs/user-manual/modules/ROOT/pages/route-template.adoc > source: https://github.com/apache/camel.git (refname: main, start path: > docs/user-manual) > [22:44:29.764] WARN (asciidoctor): skipping reference to missing attribute: > body > file: docs/components/modules/languages/pages/simple-language.adoc > source: https://github.com/apache/camel.git (refname: camel-3.11.x, start > path: docs/components) > [22:45:12.893] WARN (asciidoctor): skipping reference to missing attribute: > body > file: docs/components/modules/languages/pages/simple-language.adoc > source: https://github.com/apache/camel.git (refname: main, start path: > docs/components) > [22:45:47.775] WARN (asciidoctor): skipping reference to missing attribute: 8 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.776] WARN (asciidoctor): skipping reference to missing attribute: 4 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.776] WARN (asciidoctor): skipping reference to missing attribute: 4 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.776] WARN (asciidoctor): skipping reference to missing attribute: 4 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.776] WARN (asciidoctor): skipping reference to missing attribute: 12 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.776] WARN (asciidoctor): skipping reference to missing attribute: 8 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.776] WARN (asciidoctor): skipping reference to missing attribute: 4 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.777] WARN (asciidoctor): skipping reference to missing attribute: 3 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.777] WARN (asciidoctor): skipping reference to missing attribute: 4 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.777] WARN (asciidoctor): skipping reference to missing attribute: 12 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.777] WARN (asciidoctor): skipping reference to missing attribute: 8 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.777] WARN (asciidoctor): skipping reference to missing attribute: 4 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.777] WARN (asciidoctor): skipping reference to missing attribute: 3 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) > [22:45:47.777] WARN (asciidoctor): skipping reference to missing attribute: 3 > file: docs/modules/ROOT/pages/apis/crds-html.adoc > source: https://github.com/apache/camel-k.git (refname: main, start path: > docs) >
Re: [Website] Possible change in components page generation (preview available)
Hi David On Tue, Aug 17, 2021 at 7:42 AM David Jencks wrote: > > I’ve made a lot of progress on this and put up a preview of the current > state. Only components in the latest branch are done (not dataformats, eips, > languages, other, and not other versions). Perhaps we can create (sub)issues for outstanding work so folk can jump in and help as well? > The arrangement of, in particular, API data didn’t make much sense to me so I > reorganized it so relevant information is all together, and added a lot of > in-page links. What sometimes bothered me is that I could not point someone to an exact option in the table, perhaps this is for another time but I think it would be good to have much more anchors within the page, one of those would be for each individual option. Perhaps as a follow up on this work. > There are a couple of glitches… > - “debugging code” showing e.g. "pascalcasescheme: Twilio” I'd assume this would be trivial to fix :) > - For some reason lists don’t display properly in the first row of tables. At > https://camel-preview-1.s3.us-west-2.amazonaws.com/components/latest/twilio-component.html#_path_parameters_2_parameters > compare the apiName row and the methodName row. > > https://camel-preview-1.s3.us-west-2.amazonaws.com/components/latest/twilio-component.html > is the most complex page, and can be compared to the current site at > https://camel.apache.org/components/latest/twilio-component.html. Yeah, we could also add the enum values inline, i.e. not in a list, perhaps within a tag, not sure if it's worth spending too much of an effort on this. I'd create a follow up issue for this and any other cleanup tasks... > I haven’t published the updates needed to the Asciidoctor extension that does > the generation, so a PR is not yet feasible. Would love to see how this is shaping up, even if you have it somewhere in a draft phase it would be good to get familiar with the code. Perhaps we can create a branch on the camel-website and work on it from there? Would be easy (I think) to set up a preview via GitHub Workflow + Netlify or a Jenkins build and a staging site hosted by ASF... I've noticed that the Kamelet catalog is not rendering correctly (https://camel-preview-1.s3.us-west-2.amazonaws.com/camel-kamelets/latest/index.html), not sure if that's a CSS issue or it has something to do with the changes you're making. Thanks David for taking this on, looking forward to this, it should cut down a lot of the complexity in how we build the website and remove some of the work needed in the main camel repository. I can even see us not needing to do as many regen commits as an outcome of this! zoran -- Zoran Regvart
Re: [Website] Better error checking
Hi David, On Tue, Aug 17, 2021 at 7:53 AM David Jencks wrote: > > Related to my proposal to change how component pages are (partially) > generated I expect to be proposing to move to the latest Antora 3 alpha. In > particular this has logging and the ability to be configured to fail on log > levels, in particular warnings. This will make the xref-checker obsolete, as > logging provides more detailed information. +1 for replacing the xref-checker, we basically generate the Antora portion of the website twice, which takes up quite a bit of time; so removing the xref-checker should speedup the build. > Currently the warnings and errors from the build are: > > [22:44:07.521] WARN (asciidoctor): skipping reference to missing attribute: > myclient > file: docs/user-manual/modules/ROOT/pages/route-template.adoc > source: https://github.com/apache/camel.git (refname: main, start path: > docs/user-manual) [snip] > Currently this sort of warning is output to the console but cannot be used to > fail the build. Could we use `failure_level`[1] to fail the build? I'm taking it as a fact that most folk don't go through the build logs so not failing the build for errors (and we should fail for warnings as well IMHO) leaves us with a broken website. zoran [1] https://docs.antora.org/antora/3.0/playbook/runtime-log-failure-level/ -- Zoran Regvart
