mirror of
https://github.com/Unleash/unleash.git
synced 2024-12-28 00:06:53 +01:00
54444a395c
## Problem Our API docs are generated from a specfile that is hosted in https://us.app.unleash-hosted.com/ushosted By default the API docs UI will show that URL, which we don't want  ## Previously We ran a find-and-replace after the mdx files were generated with `replace-in-file` ## Now The previous solution is no longer possible because the openapi plugin changed. Basically, before it generated markdown files that looked like this: ``` # Create API Key https://unleash-hosted/whatever bla bla bla ``` Now it generates files that do not contain the URL and look like this: ``` import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; <Heading as={"h1"} className={"openapi__heading"} children={"Configure project access"} > </Heading> ``` which themselves get compiled. ## Solution This PR now downloads the specfile, makes a local copy, then an alters the server URL in the copy, then uses that local file to generate the docs.  I didn't want to make any changes to the actual spec logic because this essentially just a plugin quirk --- [PREVIEW LINK](https://unleash-docs-git-alvin-fix-openapi-rename-unleash-team.vercel.app/reference/api/unleash/get-addon)
109 lines
4.0 KiB
Markdown
109 lines
4.0 KiB
Markdown
# Website
|
|
|
|
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
|
|
|
|
## Installation
|
|
|
|
In a terminal, cd into the website folder of the locally cloned unleash repository and then start the installation.
|
|
|
|
```console
|
|
cd unleash/website
|
|
yarn install
|
|
```
|
|
|
|
## Generate OpenAPI docs
|
|
|
|
```console
|
|
yarn generate
|
|
```
|
|
|
|
Generate the Open API docs that live at Reference documentation > APIs > OpenAPI
|
|
|
|
## Local Development
|
|
|
|
Before running the docs the first time, you'll need to generate external documentation, as described in the [generate OpenAPI docs](#generate-openapi-docs) section.
|
|
|
|
```console
|
|
yarn start
|
|
```
|
|
|
|
Start a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
|
|
|
|
## Build
|
|
|
|
```console
|
|
yarn build
|
|
```
|
|
|
|
This command generates static content into the `build` directory and can be served using any static contents hosting service.
|
|
|
|
## Cleaning dependencies and caches
|
|
|
|
If you're upgrading many dependencies, it's always good to delete the `node_modules` directory, refresh `yarn.lock` and clean the various caches.
|
|
|
|
```console
|
|
rm -rf node_modules
|
|
rm -rf .docusaurus
|
|
rm -rf docs/reference/api/unleash
|
|
rm -rf yarn.lock
|
|
touch yarn.lock
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### `TypeError: source_default(...).bold is not a function`
|
|
|
|
If you get an error like this, it's probably due to a formatting issue within one of the markdown files. It could be
|
|
|
|
- unescaped angle brackets (markdown will try to parse `<your-key>` (when it's not quoted) as HTML, which breaks the build)
|
|
- incorrectly formatted titles or missing pieces of files
|
|
- a lot of other stuff.
|
|
|
|
```console
|
|
Component Figure was not imported, exported, or provided by MDXProvider as global scope
|
|
|
|
TypeError: source_default(...).bold is not a function
|
|
[ERROR] Unable to build website for locale en.
|
|
```
|
|
|
|
This error is very hard to debug, but there is a trick that appears to work (as shared in [this discussion on docusaurus' repo](https://github.com/facebook/docusaurus/issues/7686#issuecomment-1486771382)):
|
|
|
|
In `node_modules/@docusaurus/core/lib/client/serverEntry.js`, remove all references to `chalk`. You can use a regex replace for that, by replacing `chalk(\w|\.)+` with the empty string.
|
|
|
|
Depending on your editor, that regex might need more escapes. For instance, here's a command to run with `evil-ex` in Emacs:
|
|
|
|
```
|
|
%s/chalk\(\w\|\.\)+//g
|
|
```
|
|
|
|
For macOS `sed`, it'd be:
|
|
|
|
```shell
|
|
sed -i '' 's/chalk\(\w\|\.\)\+//g' node_modules/@docusaurus/core/lib/client/serverEntry.js
|
|
```
|
|
|
|
For GNU `sed`:
|
|
|
|
```shell
|
|
sed -i 's/chalk\(\w\|\.\)\+//g' node_modules/@docusaurus/core/lib/client/serverEntry.js
|
|
```
|
|
|
|
That might turn your error into something like this:
|
|
|
|
```console
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/change-requests.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/feature-types.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/frontend-api.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/maintenance.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/notifications.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/personal-access-tokens.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/segments.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/service-accounts.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/telemetry.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/unstable.
|
|
Component Figure was not imported, exported, or provided by MDXProvider as global scope
|
|
|
|
Error: Unexpected: cant find current sidebar in context
|
|
[ERROR] Unable to build website for locale en.
|
|
```
|