#1391: add generated doc cleaning script (#2077)

* #1391: add generated doc cleaning script

## What

The cleaning script replaces all references to the Unleash ushosted instance in the
generated OpenAPI docs. It removes extra path segments (such as leading
`/ushosted` instances) and replaces the ushosted base url with something
user-agnostic.

## Why

When we host the OpenAPI docs in our official documentation, the generated
docs shouldn't necessarily point at _one specific instance_, and especially
not one that the reader is unlikely to ever use. Instead, we can remove all
the bits that are specific to the generation source we use, and make the docs
easier to use. In particular, removing the leading `/ushosted` is likely to
save us loooots of questions.

* #1391: change env var used for generating openapi from localhost

Using NODE_ENV=development doesn't necessarily make sense, so adding
an extra variable sounds reasonable to me.

* #1391: ensure that all generation commands also clean docs

* #1391: change <your-unleash-instance-url> to <your-unleash-url>

* #1391: fix ushosted replacement: not all paths start with /api

* #1391: chore: remove potential `ushosted` ending of api url

In the event that we change the base URL of OpenAPI, so that paths
don't start with `/ushosted/`, the script should still work, changing
those paths into <your-unleash-url> too.

Additionally, remove all instances of `/ushosted` that we find. In the
event that some things switch around or whatever.

website/clean-generated-docs.js

@@ -0,0 +1,30 @@
+// Description:
+//
+// ## What
+//
+// This script replaces all references to the Unleash ushosted instance in the
+// generated OpenAPI docs. It removes extra path segments (such as leading
+// `/ushosted` instances) and replaces the ushosted base url with something
+// user-agnostic.
+//
+// ## Why
+//
+// When we host the OpenAPI docs in our official documentation, the generated
+// docs shouldn't necessarily point at _one specific instance_, and especially
+// not one that the reader is unlikely to ever use. Instead, we can remove all
+// the bits that are specific to the generation source we use, and make the docs
+// easier to use. In particular, removing the leading `/ushosted` is likely to
+// save us loooots of questions.
+const replace = require('replace-in-file');
+
+const options = {
+    files: 'docs/reference/api/**/*.api.mdx',
+    from: [
+        /\/ushosted/g,
+        /"https:\/\/us.app.unleash-hosted.com(\/ushosted)?"/g,
+        '"path":["ushosted","api"',
+    ],
+    to: ['', '"<your-unleash-url>"', '"path":["api"'],
+};
+
+replace(options);

website/docusaurus.config.js

@@ -198,7 +198,7 @@ module.exports = {
                 config: {
                     server: {
                         specPath:
-                            process.env.NODE_ENV === 'development'
+                            process.env.OPENAPI_SOURCE === 'localhost'
                                 ? 'http://localhost:4242/docs/openapi.json'
                                 : 'https://us.app.unleash-hosted.com/ushosted/docs/openapi.json',
                         outputDir: 'docs/reference/api/unleash',

website/package.json

@@ -8,10 +8,10 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
-    "build": "docusaurus gen-api-docs all && docusaurus build",
+    "build": "yarn generate && docusaurus build",
     "swizzle": "docusaurus swizzle",
-    "generate": "docusaurus gen-api-docs all",
-    "deploy": "docusaurus gen-api-docs all && docusaurus deploy",
+    "generate": "docusaurus gen-api-docs all && node clean-generated-docs.js",
+    "deploy": "yarn generate && docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
@@ -74,6 +74,7 @@
     "babel-loader": "8.2.5",
     "enhanced-resolve": "5.10.0",
     "react-router": "6.3.0",
+    "replace-in-file": "^6.3.5",
     "storybook-addon-root-attribute": "1.0.2",
     "typescript": "4.8.2"
   }

website/yarn.lock

@@ -7585,7 +7585,7 @@ glob@7.1.6:
     once "^1.3.0"
     path-is-absolute "^1.0.0"
 
-glob@^7.0.0, glob@^7.1.3, glob@^7.1.4, glob@^7.1.6:
+glob@^7.0.0, glob@^7.1.3, glob@^7.1.4, glob@^7.1.6, glob@^7.2.0:
   version "7.2.3"
   resolved "https://registry.yarnpkg.com/glob/-/glob-7.2.3.tgz#b8df0fb802bbfa8e89bd1d938b4e16578ed44f2b"
   integrity sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==
@@ -12218,6 +12218,15 @@ repeating@^2.0.0:
   dependencies:
     is-finite "^1.0.0"
 
+replace-in-file@^6.3.5:
+  version "6.3.5"
+  resolved "https://registry.yarnpkg.com/replace-in-file/-/replace-in-file-6.3.5.tgz#ff956b0ab5bc96613207d603d197cd209400a654"
+  integrity sha512-arB9d3ENdKva2fxRnSjwBEXfK1npgyci7ZZuwysgAp7ORjHSyxz6oqIjTEv8R0Ydl4Ll7uOAZXL4vbkhGIizCg==
+  dependencies:
+    chalk "^4.1.2"
+    glob "^7.2.0"
+    yargs "^17.2.1"
+
 require-directory@^2.1.1:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/require-directory/-/require-directory-2.1.1.tgz#8c64ad5fd30dab1c976e2344ffe7f792a6a6df42"
@@ -14743,7 +14752,7 @@ yargs@^16.2.0:
     y18n "^5.0.5"
     yargs-parser "^20.2.2"
 
-yargs@^17.0.1:
+yargs@^17.0.1, yargs@^17.2.1:
   version "17.5.1"
   resolved "https://registry.yarnpkg.com/yargs/-/yargs-17.5.1.tgz#e109900cab6fcb7fd44b1d8249166feb0b36e58e"
   integrity sha512-t6YAJcxDkNX7NFYiVtKvWUz8l+PaKTLiL63mJYWR2GnHq2gjEWISzsLp9wg3aY36dY1j+gfIEL3pIF+XlJJfbA==