Docusaurus Upgrade blocked. KIT pages fail to render in build process

[SebastianBezold]

There is a new version of Docusaurus available, that we want to use (see #128). There is also a PR already opened by @FaGru3n #129 Unfortunately the static build of the website fails with the new Docusaurus version.

Failing build can be seen here. We could also confirm the error locally. To reproduce, you can upgrade docusaurus locally by running npm i --save @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest

Currently, it is unknown, what causes these errors, but one guess is, that it might be caused by spaces in the file path.

@santiagoejm could you maybe help us out and analyze, if it is actually caused by spaces in file paths?

[FaGru3n]

Hi @santiagoejm tried it locally to refactor the existing paths within the kits/ without the spaces between the folder structure

unforunatly this was not the approach, so i would guess it has to do somethin with:

[ERROR] Docusaurus server-side rendering could not render static page with path /docs/kits/DataChainKit/SoftwareDevelopmentView/*. TypeError: useTabGroupChoice is not a function for all static pages

and only found this function within

I look forward to hearing from you 👍🏼

[santiagoejm]

Hi @FaGru3n, yesterday I also tried this approach and of course you know the result already, I'm happy that is confirmed by another person as well, but sadly I've found this thread in the plugin's repo. The conflict is that the plugin doesn't support yet the latest Docusaurus version.

[SebastianBezold]

Hi @santiagoejm,

there is a new comment in the thread you mentioned. Seems like the support for 2.3 docusaurus shouuld be available for trying out. Actually there is already 2.4, so maybe we can directly jump to that.

FYI @danielmiehle

Maybe we can finally remove the blocking issue and upgrade Docusaurus to an up-to-date version

[tomaszbarwicki]

Just FYI, I tried an upgrade to Docusaurus 2.4.1 and that seems to work now. However the mode has changed from night to light. Not sure where that can be fixed though.

Current (left-hand side) vs After upgrade (right-hand side)

@santiagoejm would you mind confirming on your end the plugin support works as expected?

[santiagoejm]

Hi @SebastianBezold, so good to know, I am gonna try it locally like @tomaszbarwicki suggested and figure out why the sudden change to "light mode". I am actually working on the "light theme" at the moment, nice moment to implement those 2 updates.

[SebastianBezold]

Hi @santiagoejm, great to hear, would definitely appreciate if we could finally upgrade to a new version. I guess to not break the live website in the progress, we need to combine the light theme and the upgrade in a single PR

[santiagoejm]

Hey @SebastianBezold, I actually thought the same but trying locally once the version is updated to 2.4.1 in my end I don't get the same behaviour as @tomaszbarwicki, I mean my local stays by default in dark mode as it is defined here. Do you still get the light mode as default when starting the project? Maybe the update of the version and the theme doesn't have to be necessarily related.

And the second thing is that almost all functionality works fine, except the KITs documentation that throws the next error when navigated to:

Do you also get this one?

[santiagoejm]

Oh @SebastianBezold one more question, the upgrade of the docusaurus-openapi-docs 2.0.0 is still a Beta released, been the Latest 1.7.3 that still doesn't handle docusaurus >= 2.3.0 should/can we use go for it right away?

[tomaszbarwicki]

@santiagoejm I tried another browser and dark mode is on this time, not sure why was the other way last time, could be related to some Safari settings. With regards to KITs documentation it also looks good.

[santiagoejm]

Thanks @tomaszbarwicki, well at least the theme is not affected any more, it probably was what you've mentioned. But funny thing the KITs documentation isn't? it keeps breaking in my end, did you only updated the @docusaurus/core and docusaurus/preset-classic dependencies from 2.2.0 to 2.4.1 right?

[tomaszbarwicki]

Hi @santiagoejm, that's correct, only these two: "@docusaurus/core": "^2.4.0", "@docusaurus/preset-classic": "^2.4.0",

Which got upgraded as you pointed to 2.4.1:

├── @docusaurus/core@2.4.1 ├── @docusaurus/preset-classic@2.4.1

[tomaszbarwicki]

hey @santiagoejm, just a follow up on the thread, any update? success?

[santiagoejm]

Hi @tomaszbarwicki sorry for the late response, I was ooo and still catching on with the messages. I can tell you that the update of docusaurus is now working properly for me; but the issue arise with the open-api plugin. I am sure when you update locally the docusaurus version to ^2.4.0 everything works fine but the page crashes when you navigate to any KIT -> Development View -> api definition right? That is why we need to update the open-api plugin, but as you can see here, the plugin's version that can handle the latest docusaurus version is still in beta and is definitely buggy, when I update it to 2.0.0-beta.3 the project crashes due to some conflict with the react-live package. You can easily reproduce it be updating the following dependencies:

"docusaurus-plugin-openapi-docs": "2.0.0-beta.3",
"docusaurus-theme-openapi-docs": "2.0.0-beta.3",

It would be great if you can confirm this in your local as well?

Cheers!

[tomaszbarwicki]

Hi @santiagoejm, thanks for reply! I get your point now and indeed face the same issue "This page crashed." for provided location. Was also able to reproduce the crash after openapi upgrade to beta version:

I believe in that case we need to postpone the upgrade until stable open-api plugin version is released, pls let me know your thoughts on that.

[santiagoejm]

Hi @tomaszbarwicki, yes indeed I think we should wait until a stable open-api plugin released is available, this has been a blocker for a while now but hopefully pretty soon it's gonna be solved

[almadigabor]

Hi All! I'd like to talk about the Docusaurus upgrade topic again. There has been some changes lately, like Docusaurus v3 and docusaurus-openapi-docs v2 has been released.

I've created a branch where I tried to make the upgrade to Docusaurus 2.4.3 as the openapi plugin v2 does not support Docusaurus v3. While running npm start (also removed node_modules, changed to node 18 and ran npm i) I got the following error:

Module not found: Error: Can't resolve 'react/jsx-runtime' in '<REPO>/eclipse-tractusx.github.io/node_modules/docusaurus-theme-openapi-docs/node_modules/react-live/dist'
Did you mean 'jsx-runtime.js'?
BREAKING CHANGE: The request 'react/jsx-runtime' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.

This would be resolvable either by

• modifying the webpack config but it is not ejected and we do not want that
• upgrading to React 18 but Docusaurus v2.x.x. does not support that
• upgrading to Docusaurus v3 but the openapi plugin v2 does not support that

We should really find a maintainer for this page because all it's dependencies are getting out of date which could late to security issues. One solution would be moving the openapi components to SwaggerHub and then we could get rid of the openapi plugin dependency which is the main reason we are blocked from upgrading everything else. Suggestions are welcome and I'll send a mail to the mailing list as well.

[arnoweiss]

I heard there'd be a move away from the plugin and use swaggerhub instead. Is there any news on this?

[mhellmeier]

I heard there'd be a move away from the plugin and use swaggerhub instead. Is there any news on this?

Valid point! Would be great to have a decision here (maybe as a TRG?) for the teams working on the KITs for the next release to prepare everything.

[danielmiehle]

Hi all, thank you for your patience.

Correct, we want to switch to the Swagger Hub as soon as possible (but not for Release 23.12). We will work with the System Team to provide all relevant information and timeline after the release.

Stay tuned.

Best, Daniel