OpenAPI pages are crashed with Docusaurus v2.2.0 #323
Comments
|
🎉 Thanks for opening your first issue here! Welcome to the community! |
hdkshingala
changed the title
|
I'm having the same issue, and I also can't run the I'm thinking it's something to do with the |
|
@hdkshingala thanks for reporting the issue. Although Docusaurus is supposed to respect semantic versioning now, they apparently still introduce breaking changes, at least for plugin maintainers. The fix for supporting v2.2.0 should be straightforward but I am not sure how we can make it backwards compatible with v2.1.0 and v2.0.1. @calthejuggler, v2.2.0 is currently not supported due to a breaking change introduced by Docusaurus. That is why the build fails. |
|
Hi all, just merged support for v2.2.0 into main. Would appreciate if anyone could test using canary release |
|
@sserrata This may be unrelated, but I think it's a continuation of the same issue. I've been having some issues today (as mentioned in #337), but I've found a potential workaround and have made some progress. As far as I've gotten now, I've tried out both
From what I can tell, your first fix was successful, but there's more hooks that have been moved around. I've been trying to connect the threads, and it seems somewhat related to what's mentioned in this issue about a similar breakage. |
|
Hi @thomasheartman, can you share your upgrade path or process? I noticed that if you run the suggested upgrade commands (pictured below) that not all dependencies are upgraded to 2.2.0. I'm still experimenting but I found that simply running Upgrading this way seems to not update all Docusaurus dependencies to 2.2.0:
|
|
Sure! I just went into the package.json and did it manually 💁🏼 I'm trying with |
|
@sserrata So I've tried again and also made sure that all the deps are on the same version. it runs fine in development mode, but when running docusaurus build, it fails. Does that sound familiar? |
|
Interestingly, I'm getting this error now: It's kinda inscrutable, but better than |
|
What version of |
|
I've tried 1.4.3 and 1.4.1. I think I've regenerated the API docs every time, but I'll give it another go just to make sure 🙋🏼 |
|
Update: regenerating the docs doesn't seem to have any effect. That is: the issue still happens. |
|
Is it still working in dev? What's the build error you're seeing? |
|
If you haven't already, you might want to try some variation of: |
|
Yeah, it builds fine in dev and visiting the generated pages doesn't cause any issues either. The error I'm seeing is: Which isn't very helpful at all. if I go into After clearing |
|
Now, I just want to jump in and say that this might not be an issue with your package at this point, and it might just have been happening at the same time as the other error, but because the error messages are so vague and don't actually say where the error is, it gets a lot harder. I thought that building with the |
|
The plot thickens...now I am seeing the same error but only when attempting to build the demo locally: The weird thing is that it build in prod and in deploy previews. |
|
Update: ended up being caused by some old generated files I forgot to cleanup in between tests. Worked after I deleted them. |
|
Thanks, @sserrata! Unfortunately, we're seeing the issue both locally and when building docs in CI. I've also completely removed the generated directories a few times to avoid having outdated files lying around. We did have a similar issue once before, where it was caused by an empty file, but |
|
So I'm making some progress, and it looks like the error is indeed related to this package: I found that
So I'm thinking that it may be related to the configuration somehow. For reference, here's what I'm using: ConfigurationIn plugins: [
// elided: redirect plugin configuration
[
'docusaurus-plugin-openapi-docs',
{
id: 'api-operations',
docsPluginId: 'classic',
config: {
server: {
specPath: 'https://us.app.unleash-hosted.com/ushosted/docs/openapi.json',
outputDir: 'docs/reference/api/unleash',
sidebarOptions: {
groupPathsBy: 'tag',
categoryLinkSource: 'tag',
},
},
},
},
],
],
themes: ['docusaurus-theme-openapi-docs']In {
label: 'OpenAPI docs',
collapsed: true,
type: 'category',
link: {
title: 'Unleash Server APIs',
type: 'generated-index',
description:
'Generated API docs based on the Unleash OpenAPI schema.',
slug: '/reference/api/unleash',
},
items: require('./docs/reference/api/unleash/sidebar.js'),
}As mentioned in the file, the source spec we use for generation is Does that look right? Is there something that stands out to you as potentially causing these issues? @sserrata I also realize that this is probably not the same issue as the one the OP reported anymore: should I open another one? Sorry for overtaking this thread 🙇🏼 |
|
@sserrata I think I found the issue 🙋🏼 I'll try and explain it here, but in short: the plugin generated two tag files it didn't reference. That would also explain why sidebar reference couldn't be found. The root causeThe OpenAPI spec we use to generate the docs has a number of tags listed at the root level. This is necessary for this plugin to pick up tag categories and is, as far as I can tell, also how it should be done. However, not all of those tags are in use. Specifically, there's 2 tags that are not. When the plugin generates docs from the spec, it generates pages for all endpoints and all tags and groups them by tag. However, it seems likely that if a tag doesn't have any associated endpoints, then it won't get added to the sidebar because there's no endpoint that references it. But the doc files for these tags do end up lying around in the directory regardless, and when docusaurus tries to pick up the files in the generated directory, it also tries to pick up the unused tag files. But because they're not part of a sidebar, they end up throwing errors because they can't find the sidebar context. How I found itThe fact that I got more instances of the error message without the sidebar ref than with it made me pay more attention to the number of errors. I decided to check how many files were in the generated directory and how many files were referenced from the generated sidebar. Turns out the difference there was 2: there were two generated files in the directory that the sidebar didn't reference. At this point, it was easy enough to try and delete those files before rebuilding, and wouldn't you know: it worked! Our use caseNow, why do we have tags that are unused in the root spec? Can't we just remove them? That's a good question with a bit of a complicated answer. Unleash uses an open core model and the OpenAPI integration is part of that open core. The closed-source parts of Unleash are located in another repo and extend the open-source distribution. Because the OpenAPI spec is configured in the open-source part, enterprise-only tags etc also need to be configured there. Then, when the changes are absorbed into enterprise, we can use the tags there. It gets more complicated because we use an enterprise instance to generate the docs (because we want enterprise-endpoints to be listed too). The instance uses the latest released instance of Unleash to have the docs most accurately reflect the current state of things. So, in this case, the tags have been added, but not yet used by any endpoints, which suddenly causes this build failure. We can add the tags to the enterprise-version, but the spec wouldn't be updated before the next release regardless, which will probably be in a week or so. This isn't an ideal setup, but .. it is what it is. I'll make some changes now to try and remove any tags we don't actually use, but it'll take some time for the changes to propagate. Expectations for this pluginI would not expect the plugin to cause compilation issues when this happens. It could certainly log some warnings if it wanted (during doc generation process), but it shouldn't stop the build from working. I think I would expect one of these two outcomes:
What do you think? I'd consider this a bug with the plugin, but I'm happy for you to have a different take on it. Feel free to spin this out into a separate issue if you want to 😄 |
## Issue
So, we've got an issue with our docs build not working. When building
for production, we get an error that looks a little bit like this:
```
$ docusaurus build
[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
Compiled with some errors in 40.85s
TypeError: source_default(...).bold is not a function
TypeError: source_default(...).bold is not a function
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Users/thomas/projects/work/unleash/website/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.2.0
Node version: v16.14.0
error Command failed with exit code 1.
```
Which isn't very helpful at all. If you go into
`/node_modules/@docusaurus/core/lib/client/serverEntry.js` and modify
the `render` function to log the actual error and remove anything
chalk-related, you get this instead:
```
$ docusaurus build
[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
Compiled with some errors in 44.62s
Actual error: Error: Unexpected: cant find current sidebar in context
at useCurrentSidebarCategory (main:11618:247)
at MDXContent (main:38139:1593)
at Fb (main:149154:44)
at Ib (main:149156:254)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
Actual error: Error: Unexpected: cant find current sidebar in context
at useCurrentSidebarCategory (main:11618:247)
at MDXContent (main:38513:1469)
at Fb (main:149154:44)
at Ib (main:149156:254)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
Error: Unexpected: cant find current sidebar in context
Error: Unexpected: cant find current sidebar in context
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Users/thomas/projects/work/unleash/website/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.2.0
Node version: v16.14.0
error Command failed with exit code 1.
```
That's better, but it's still not very clear.
## Getting more info
We've had problems with a similar error message before. Last time it was
caused by an empty file that docusaurus couldn't process.
A similar issue has also been described in [ this docusaurus GitHub
issue ](facebook/docusaurus#7686). That's also
what gave me the idea of changing the logging in the dependency.
I'm currently unsure whether this is caused by the openapi docs or
something else. I've been in touch with the [openapi plugin
maintainer](PaloAltoNetworks/docusaurus-openapi-docs#323)
and he has been able to see the same error when building for prod
locally, but it was due to some old generated files.
Worth noting: this only seems to affect the prod build. Building for dev
(`yarn docusaurus start`) works just fine. It also fails locally **and**
in CI, so it _is_ an issue.
## Updating the logging
To get better logging, you can go into the
`/node_modules/@docusaurus/core/lib/client/serverEntry.js` file and
update the `render` function from
```js
export default async function render(locals) {
try {
return await doRender(locals);
}
catch (err) {
// We are not using logger in this file, because it seems to fail with some
// compilers / some polyfill methods. This is very likely a bug, but in the
// long term, when we output native ES modules in SSR, the bug will be gone.
// prettier-ignore
console.error(chalk.red(`${chalk.bold('[ERROR]')} Docusaurus server-side rendering could not render static page with path ${chalk.cyan.underline(locals.path)}.`));
const isNotDefinedErrorRegex = /(?:window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
if (isNotDefinedErrorRegex.test(err.message)) {
// prettier-ignore
console.info(`${chalk.cyan.bold('[INFO]')} It looks like you are using code that should run on the client-side only.
To get around it, try using ${chalk.cyan('`<BrowserOnly>`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#browseronly')}) or ${chalk.cyan('`ExecutionEnvironment`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#executionenvironment')}).
It might also require to wrap your client code in ${chalk.cyan('`useEffect`')} hook and/or import a third-party library dynamically (if any).`);
}
throw err;
}
}
```
to
```js
export default async function render(locals) {
try {
return await doRender(locals);
}
catch (err) {
console.error(err)
throw err;
}
}
```
That'll yield the errors about the current sidebar in context.
## Root cause
Found the issue! 🙋🏼 It's explained in [this comment on the openapi docs
integration](PaloAltoNetworks/docusaurus-openapi-docs#323 (comment))
for now, but in short: we have tags defined that we don't use. They're
being picked up by docusaurus, but don't have the proper context. That's
causing this.
The previously mentioned comment is included here for easy finding in
the future:
### Root cause explanation
The OpenAPI spec we use to generate the docs has a number of tags listed
at the root level. This is necessary for this plugin to pick up tag
categories and is, as far as I can tell, also how it _should_ be done.
However, not all of those tags are in use. Specifically, there's 2 tags
that are not.
When the plugin generates docs from the spec, it generates pages for all
endpoints and all tags and groups them by tag. However, it seems likely
that if a tag doesn't have any associated endpoints, then it won't get
added to the sidebar because there's no endpoint that references it.
But the doc files for these tags do end up lying around in the directory
regardless, and when docusaurus tries to pick up the files in the
generated directory, it also tries to pick up the unused tag files. But
because they're not part of a sidebar, they end up throwing errors
because they can't find the sidebar context.
### How I found it
The fact that I got more instances of the error message without the
sidebar ref than with it made me pay more attention to the number of
errors. I decided to check how many files were in the generated
directory and how many files were referenced from the generated sidebar.
Turns out the difference there was **2**: there were two generated files
in the directory that the sidebar didn't reference.
At this point, it was easy enough to try and delete those files before
rebuilding, and wouldn't you know: it worked!
### Our use case
Now, why do we have tags that are unused in the root spec? Can't we just
remove them?
That's a good question with a bit of a complicated answer. Unleash uses
an open core model and the OpenAPI integration is part of that open
core. The closed-source parts of Unleash are located in another repo and
extend the open-source distribution.
Because the OpenAPI spec is configured in the open-source part,
enterprise-only tags etc also need to be configured there. Then, when
the changes are absorbed into enterprise, we can use the tags there.
It gets more complicated because we use an enterprise instance to
generate the docs (because we want enterprise-endpoints to be listed
too). The instance uses the latest released instance of Unleash to have
the docs most accurately reflect the current state of things.
So, in this case, the tags have been added, but not yet used by any
endpoints, which suddenly causes this build failure. We can add the tags
to the enterprise-version, but the spec wouldn't be updated before the
next release regardless, which will probably be in a week or so.
This isn't an ideal setup, but .. it is what it is.
## Solutions and workarounds
As mentioned in the previous section, the reason the build was failing
was that there were unused tag files that docusaurus tried to include in
the build. Because they don't belong to a sidebar, the compilation
failed.
I've reported the issue to the openapi plugin maintainers and am waiting
for a response.
However, it seems that having unused root tags declared is invalid
according to the spec, so it's something we should look into fixing in
the future.
### Current workaround: cleaning script
The current workaround is to extend the api cleaning script to manually
remove the unused tag files.
### Ideal solution: filter root-level tags
Ideally, we shouldn't list unused OpenAPI tags on the root level at all.
However, because of the way we add root-level tags (as a predefined,
static lists, refer to `src/lib/openapi/index.ts`) and endpoints
(dynamically added at runtime) today, we don't really have a clear way
to filter the list of tags. This gets even more complicated when taking
the enterprise functionality and the potential extra tags they must
have.
This is, however, something that should definitely be looked into.
Working with OpenAPI across multipile repos is already troublesome, so
this is just yet another thing to look into.
|
Hi @thomasheartman, thanks for the detailed write up - you helped me understand that this is a regression bug introduced in #276. I think it can be refactored to exclude any global tags that are not referenced by an operation. |
Yes, that should cover it 😁 🙌 |
|
@thomasheartman fix is included in |
|
Wow, amazing! I'll give it a spin on Monday and look forward to the next release, then 😄 Is there a scheduled date for it (or a rough estimation)? |
It's available now: v1.4.4 |
|
Legend 🔥 |
|
Upgraded out setup to Docusaurus 2.2.0 and Plugin v1.4.4 and it is working as expected now. Thanks a lot @sserrata for providing the fix real quick. |
|
As I used this plugin in docusaurus's latest version (2.3.1) but I am facing the same issue after installing the plugin, so anyone can find any solution in the mentioned version of docusaurus(2.3.1), If yes then please let me know about this, thanks.
|
|
@aj-hops You'll need to upgrade to the |
Describe the bug
The OpenAPI pages are crashing when we upgraded the Docusaurus from v2.1.0 to v2.2.0.
Expected behavior
The plugin should work fine and should show the pages correctly.
Current behavior
The OpenAPI related pages get crashed with below error:
Steps to reproduce
Your Environment
We have tried using the latest v1.4.1 but faced #315 so couldn't check with the latest version.
The text was updated successfully, but these errors were encountered: