From 0a99dfd6e3015213ba4e9b4c24454ac90fbdc07f Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 20 Sep 2022 12:43:39 +0200 Subject: [PATCH] #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 to * #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 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 | 30 ++++++++++++++++++++++++++++++ website/docusaurus.config.js | 2 +- website/package.json | 7 ++++--- website/yarn.lock | 13 +++++++++++-- 4 files changed, 46 insertions(+), 6 deletions(-) create mode 100644 website/clean-generated-docs.js diff --git a/website/clean-generated-docs.js b/website/clean-generated-docs.js new file mode 100644 index 0000000000..441bcf830b --- /dev/null +++ b/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: ['', '""', '"path":["api"'], +}; + +replace(options); diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index bf5d7f2f34..6657842766 100644 --- a/website/docusaurus.config.js +++ b/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', diff --git a/website/package.json b/website/package.json index 3325250ff9..899c77fbc1 100644 --- a/website/package.json +++ b/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" } diff --git a/website/yarn.lock b/website/yarn.lock index ae11d058e4..cf46d5367f 100644 --- a/website/yarn.lock +++ b/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==