Merge pull request #567 from influxdata/fix/doc_references

fix(docs): repair generated API documentation so that links between packages are rendered
influxdata · Sep 13, 2022 · bf92b0a · bf92b0a
2 parents d5a5382 + 1a144ff
commit bf92b0a
Show file tree

Hide file tree

Showing 7 changed files with 114 additions and 47 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 ## 1.30.0 [unreleased]
 
+### Bug Fixes
+
+1. [#567](https://github.com/influxdata/influxdb-client-js/pull/567): Repair generated API documentation so that links between packages are rendered.
+
 ## 1.29.0 [2022-08-25]
 
 ### Features

diff --git a/package.json b/package.json
@@ -40,7 +40,7 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^18",
-    "@microsoft/api-documenter": "^7.18.3",
+    "@microsoft/api-documenter": "^7.19.12",
     "gh-pages": "^4.0.0",
     "lerna": "^5.0.0",
     "prettier": "^2.7.1",

diff --git a/packages/apis/package.json b/packages/apis/package.json
@@ -54,7 +54,7 @@
   },
   "devDependencies": {
     "@influxdata/influxdb-client": "^1.29.0",
-    "@microsoft/api-extractor": "^7.28.4",
+    "@microsoft/api-extractor": "^7.31.0",
     "@types/mocha": "^9.1.1",
     "@typescript-eslint/eslint-plugin": "^5.29.0",
     "@typescript-eslint/parser": "^5.29.0",

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -54,7 +54,7 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.28.4",
+    "@microsoft/api-extractor": "^7.31.0",
     "@types/chai": "^4.2.5",
     "@types/mocha": "^9.1.1",
     "@types/sinon": "^10.0.13",

diff --git a/packages/giraffe/package.json b/packages/giraffe/package.json
@@ -46,7 +46,7 @@
   "devDependencies": {
     "@influxdata/giraffe": "*",
     "@influxdata/influxdb-client": "^1.29.0",
-    "@microsoft/api-extractor": "^7.28.4",
+    "@microsoft/api-extractor": "^7.31.0",
     "@types/chai": "^4.2.5",
     "@types/mocha": "^9.1.1",
     "@types/react": "^16.9.55",

diff --git a/scripts/fix-extracted-api-files.js b/scripts/fix-extracted-api-files.js
@@ -2,24 +2,58 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 const path = require('path')
 const fs = require('fs')
+const referenceIds = {}
+let fixedReferenceCount = 0
+let fixedMarkdownLinks = 0
+
+const ignoredReferencePackages = [
+  '!' /* ts&js builtin types */,
+  '@influxdata/giraffe!' /* giraffe references */,
+  '@influxdata/influxdb-client!~__global' /*ignore global symbol declaration in packages/core/src/observable/symbol.ts */,
+]
+const mappedReferences = {
+  // defect in api-extractor naming
+  '@influxdata/influxdb-client!FLUX_VALUE':
+    '@influxdata/influxdb-client!FLUX_VALUE:var',
+  '@influxdata/influxdb-client!Headers:type':
+    '@influxdata/influxdb-client!Headers_2:type',
+}
 
 const markdownLinkRE = /\[([^\]]*)\]\(([^)]*)\)/g
 function changeMarkdownLinks(text) {
   if (text) {
     // changes markdown style [text](link) to tsdoc {@link URL | text }
     return text.replace(markdownLinkRE, (match, text, link) => {
       const retVal = `{@link ${link} | ${text} }`
-      console.log(` ${match} => ${retVal}`)
+      console.log(` CHANGED ${match} => ${retVal}`)
+      fixedMarkdownLinks++
       return retVal
     })
   }
   return text
 }
 
-function replaceInExtractorFile(file) {
-  const data = fs.readFileSync(file, 'utf8')
-  const json = JSON.parse(data)
-  console.log(`correct: ${file}`)
+function storeCanonicalReferences(json, references) {
+  function walk(obj) {
+    if (typeof obj === 'object') {
+      if (Array.isArray(obj)) {
+        obj.forEach(walk)
+      } else {
+        const canonicalReference = obj['canonicalReference']
+        if (canonicalReference && obj['kind'] && obj['kind'] !== 'Reference') {
+          references[canonicalReference] = true
+        }
+        for (const key in obj) {
+          walk(obj[key])
+        }
+      }
+    }
+  }
+  walk(json)
+}
+
+function fixExtractedFile(file, json, errors = []) {
+  console.log(`\nCheck and correct: ${file}`)
 
   function replaceObject(obj) {
     if (typeof obj === 'object') {
@@ -28,14 +62,32 @@ function replaceInExtractorFile(file) {
       } else {
         if (obj['kind'] === 'Reference') {
           const canonicalReference = obj['canonicalReference']
-          if (canonicalReference.indexOf('!default:') > 0) {
-            const text = obj['text']
-            const replaced = canonicalReference.replace(
-              /!(default):/,
-              `!${text}:`
-            )
-            console.log(` ${canonicalReference} => ${replaced}`)
-            obj.canonicalReference = replaced
+          if (canonicalReference && !referenceIds[canonicalReference]) {
+            if (canonicalReference.indexOf('!~') > 0) {
+              const replaced = canonicalReference.replace('!~', '!')
+              if (referenceIds[replaced]) {
+                fixedReferenceCount++
+                console.log(` FIXED ${canonicalReference} => ${replaced}`)
+                obj.canonicalReference = replaced
+                return
+              }
+            }
+            const mapped = mappedReferences[canonicalReference]
+            if (mapped && referenceIds[mapped]) {
+              fixedReferenceCount++
+              console.log(` FIXED ${canonicalReference} => ${mapped}`)
+              obj.canonicalReference = mapped
+              return
+            }
+            for (const ignoredPackage of ignoredReferencePackages) {
+              if (canonicalReference.startsWith(ignoredPackage)) {
+                return
+              }
+            }
+            // report unresolved references
+            const msg = ` MISSING ${canonicalReference}`
+            errors.push(`${file}: ${msg}`)
+            console.log(msg)
           }
         } else {
           for (const key in obj) {
@@ -56,6 +108,23 @@ function replaceInExtractorFile(file) {
 
 const docsDir = path.resolve(__dirname, '..', 'docs')
 const files = fs.readdirSync(docsDir).filter((x) => /\.api\.json$/.test(x))
-files.forEach((file) => {
-  replaceInExtractorFile(path.resolve(docsDir, file))
-})
+const fileToJson = files.reduce((acc, file) => {
+  file = path.resolve(docsDir, file)
+  const json = JSON.parse(fs.readFileSync(file, 'utf8'))
+  acc[file] = json
+  storeCanonicalReferences(json, referenceIds)
+  return acc
+}, {})
+
+const errors = []
+for (const [file, json] of Object.entries(fileToJson)) {
+  fixExtractedFile(file, json, errors)
+}
+
+console.info('Fixed markdown links: ' + fixedMarkdownLinks)
+console.info('Fixed references: ' + fixedReferenceCount)
+if (errors.length) {
+  console.error(`\n\nERRORS:`)
+  errors.forEach((e) => console.error(e))
+  process.exit(1)
+}
diff --git a/yarn.lock b/yarn.lock
@@ -990,37 +990,37 @@
     npmlog "^6.0.2"
     write-file-atomic "^4.0.1"
 
-"@microsoft/api-documenter@^7.18.3":
-  version "7.19.5"
-  resolved "https://registry.yarnpkg.com/@microsoft/api-documenter/-/api-documenter-7.19.5.tgz#c8736c50e5dda1b4b856beb069952dc3e723a5e7"
-  integrity sha512-MYEsoZ8b7XvrvRmsTlodmY1OZHa5o1IW8SoyuCEpsTKaYh+mSq7fHjLzBdvS1Vk+Ses0/gzhzZAyz1n1CRLE9g==
+"@microsoft/api-documenter@^7.19.12":
+  version "7.19.12"
+  resolved "https://registry.yarnpkg.com/@microsoft/api-documenter/-/api-documenter-7.19.12.tgz#6e23eb01392dbb48b8fc781a9f70eabd134854bd"
+  integrity sha512-QrYBmjMhg3rVgevHaG+4ltIiyGClbM+mJIM8f/rmwT9Q0oDhlUbBc1/AqHRrTiuV960+qhC0l3YzMoO0awh7eQ==
   dependencies:
-    "@microsoft/api-extractor-model" "7.23.1"
+    "@microsoft/api-extractor-model" "7.24.0"
     "@microsoft/tsdoc" "0.14.1"
-    "@rushstack/node-core-library" "3.50.2"
+    "@rushstack/node-core-library" "3.51.1"
     "@rushstack/ts-command-line" "4.12.2"
     colors "~1.2.1"
     js-yaml "~3.13.1"
     resolve "~1.17.0"
 
-"@microsoft/api-extractor-model@7.23.1":
-  version "7.23.1"
-  resolved "https://registry.yarnpkg.com/@microsoft/api-extractor-model/-/api-extractor-model-7.23.1.tgz#d93704882241e7720094d41c7005b07eb593c073"
-  integrity sha512-axlZ33H2LfYX7goAaWpzABWZl3JtX/EUkfVBsI4SuMn3AZYBJsP5MVpMCq7jt0PCefWGwwO+Rv+lCmmJIjFhlQ==
+"@microsoft/api-extractor-model@7.24.0":
+  version "7.24.0"
+  resolved "https://registry.yarnpkg.com/@microsoft/api-extractor-model/-/api-extractor-model-7.24.0.tgz#df71615f7c7d2c4f520c8b179d03a85efcdaf452"
+  integrity sha512-lFzF5h+quTyVB7eaKJkqrbQRDGSkrHzXyF8iMVvHdlaNrodGeyhtQeBFDuRVvBXTW2ILBiOV6ZWwUM1eGKcD+A==
   dependencies:
     "@microsoft/tsdoc" "0.14.1"
     "@microsoft/tsdoc-config" "~0.16.1"
-    "@rushstack/node-core-library" "3.50.2"
+    "@rushstack/node-core-library" "3.51.1"
 
-"@microsoft/api-extractor@^7.28.4":
-  version "7.29.3"
-  resolved "https://registry.yarnpkg.com/@microsoft/api-extractor/-/api-extractor-7.29.3.tgz#f91ca61833c170c6c47a0fc064fa010460a11457"
-  integrity sha512-PHq+Oo8yiXhwi11VQ1Nz36s+aZwgFqjtkd41udWHtSpyMv2slJ74m1cHdpWbs2ovGUCfldayzdpGwnexZLd2bA==
+"@microsoft/api-extractor@^7.31.0":
+  version "7.31.0"
+  resolved "https://registry.yarnpkg.com/@microsoft/api-extractor/-/api-extractor-7.31.0.tgz#a4dd2af2e176a330652a19f9254f77d4fdcea06f"
+  integrity sha512-1gVDvm/eKmntBn5X5Rc+XDREm9gfxQ/BQfGFf7Rf4uWvJc4Q4GxidC3lBODYDOcikjG983bzbo0xTu5BS8J93Q==
   dependencies:
-    "@microsoft/api-extractor-model" "7.23.1"
+    "@microsoft/api-extractor-model" "7.24.0"
     "@microsoft/tsdoc" "0.14.1"
     "@microsoft/tsdoc-config" "~0.16.1"
-    "@rushstack/node-core-library" "3.50.2"
+    "@rushstack/node-core-library" "3.51.1"
     "@rushstack/rig-package" "0.3.14"
     "@rushstack/ts-command-line" "4.12.2"
     colors "~1.2.1"
@@ -1351,10 +1351,10 @@
     node-addon-api "^3.2.1"
     node-gyp-build "^4.3.0"
 
-"@rushstack/node-core-library@3.50.2":
-  version "3.50.2"
-  resolved "https://registry.yarnpkg.com/@rushstack/node-core-library/-/node-core-library-3.50.2.tgz#43df3f8422898a448114fcb9c7d4e967625da585"
-  integrity sha512-+zpZBcaX5s+wA0avF0Lk3sd5jbGRo5SmsEJpElJbqQd3KGFvc/hcyeNSMqV5+esJ1JuTfnE1QyRt8nvxFNTaQg==
+"@rushstack/node-core-library@3.51.1":
+  version "3.51.1"
+  resolved "https://registry.yarnpkg.com/@rushstack/node-core-library/-/node-core-library-3.51.1.tgz#e123053c4924722cc9614c0091fda5ed7bbc6c9d"
+  integrity sha512-xLoUztvGpaT5CphDexDPt2WbBx8D68VS5tYOkwfr98p90y0f/wepgXlTA/q5MUeZGGucASiXKp5ysdD+GPYf9A==
   dependencies:
     "@types/node" "12.20.24"
     colors "~1.2.1"
@@ -1363,7 +1363,6 @@
     jju "~1.4.0"
     resolve "~1.17.0"
     semver "~7.3.0"
-    timsort "~0.3.0"
     z-schema "~5.0.2"
 
 "@rushstack/[email protected]":
@@ -6065,11 +6064,6 @@ through@2, "through@>=2.2.7 <3", through@^2.3.4, through@^2.3.6:
   resolved "https://registry.yarnpkg.com/through/-/through-2.3.8.tgz#0dd4c9ffaabc357960b1b724115d7e0e86a2e1f5"
   integrity sha1-DdTJ/6q8NXlgsbckEV1+Doai4fU=
 
-timsort@~0.3.0:
-  version "0.3.0"
-  resolved "https://registry.yarnpkg.com/timsort/-/timsort-0.3.0.tgz#405411a8e7e6339fe64db9a234de11dc31e02bd4"
-  integrity sha1-QFQRqOfmM5/mTbmiNN4R3DHgK9Q=
-
 tmp@^0.0.33:
   version "0.0.33"
   resolved "https://registry.yarnpkg.com/tmp/-/tmp-0.0.33.tgz#6d34335889768d21b2bcda0aa277ced3b1bfadf9"