From 48cae63645a3a387e79a0afc6c89bcd3653e52c1 Mon Sep 17 00:00:00 2001 From: Pavel Zavora Date: Tue, 13 Sep 2022 07:56:52 +0200 Subject: [PATCH 1/6] fix: detect and repair wrong documentation references --- scripts/fix-extracted-api-files.js | 76 ++++++++++++++++++++++++------ 1 file changed, 61 insertions(+), 15 deletions(-) diff --git a/scripts/fix-extracted-api-files.js b/scripts/fix-extracted-api-files.js index 6ff8b77c8..424373464 100644 --- a/scripts/fix-extracted-api-files.js +++ b/scripts/fix-extracted-api-files.js @@ -2,6 +2,12 @@ /* eslint-disable @typescript-eslint/no-var-requires */ const path = require('path') const fs = require('fs') +const referenceIds = {} + +const ignoredReferencePackages = [ + '!' /* ts&js builtin types */, + '@influxdata/giraffe!' /* giraffe references */, +] const markdownLinkRE = /\[([^\]]*)\]\(([^)]*)\)/g function changeMarkdownLinks(text) { @@ -9,16 +15,33 @@ function changeMarkdownLinks(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}`) return retVal }) } return text } -function replaceInExtractorFile(file) { - const data = fs.readFileSync(file, 'utf8') - const json = JSON.parse(data) +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(`correct: ${file}`) function replaceObject(obj) { @@ -28,14 +51,22 @@ 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('!~', '!') + console.log(` FIXED ${canonicalReference} => ${replaced}`) + obj.canonicalReference = replaced + return + } + // report unresolved reference + for (const ignoredPackage of ignoredReferencePackages) { + if (canonicalReference.startsWith(ignoredPackage)) { + return + } + } + const msg = ` MISSING ${canonicalReference}` + errors.push(`${file}: ${msg}`) + console.log(msg) } } else { for (const key in obj) { @@ -56,6 +87,21 @@ 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) +} + +if (errors.length) { + console.error(`\n\nERRORS:`) + errors.forEach((e) => console.error(e)) + process.exit(1) +} From e739bf969d35416b6ca1adb9c4d03a8cf8edc816 Mon Sep 17 00:00:00 2001 From: Pavel Zavora Date: Tue, 13 Sep 2022 08:02:03 +0200 Subject: [PATCH 2/6] chore: improve output format --- scripts/fix-extracted-api-files.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/fix-extracted-api-files.js b/scripts/fix-extracted-api-files.js index 424373464..32f1c5c47 100644 --- a/scripts/fix-extracted-api-files.js +++ b/scripts/fix-extracted-api-files.js @@ -42,7 +42,7 @@ function storeCanonicalReferences(json, references) { } function fixExtractedFile(file, json, errors = []) { - console.log(`correct: ${file}`) + console.log(`\nCheck and correct: ${file}`) function replaceObject(obj) { if (typeof obj === 'object') { From 56267eb3b8a4ca70db6ee7dc8cdc027af24e7d2b Mon Sep 17 00:00:00 2001 From: Pavel Zavora Date: Tue, 13 Sep 2022 09:10:10 +0200 Subject: [PATCH 3/6] chore: print total number of fixes applied to api-extractor results --- scripts/fix-extracted-api-files.js | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/scripts/fix-extracted-api-files.js b/scripts/fix-extracted-api-files.js index 32f1c5c47..2c271d26d 100644 --- a/scripts/fix-extracted-api-files.js +++ b/scripts/fix-extracted-api-files.js @@ -3,6 +3,8 @@ const path = require('path') const fs = require('fs') const referenceIds = {} +let fixedReferenceCount = 0 +let fixedMarkdownLinks = 0 const ignoredReferencePackages = [ '!' /* ts&js builtin types */, @@ -16,6 +18,7 @@ function changeMarkdownLinks(text) { return text.replace(markdownLinkRE, (match, text, link) => { const retVal = `{@link ${link} | ${text} }` console.log(` CHANGED ${match} => ${retVal}`) + fixedMarkdownLinks++ return retVal }) } @@ -54,6 +57,7 @@ function fixExtractedFile(file, json, errors = []) { if (canonicalReference && !referenceIds[canonicalReference]) { if (canonicalReference.indexOf('!~') > 0) { const replaced = canonicalReference.replace('!~', '!') + fixedReferenceCount++ console.log(` FIXED ${canonicalReference} => ${replaced}`) obj.canonicalReference = replaced return @@ -100,6 +104,8 @@ 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)) From da94357607e5c9d6ca36e499f53e78ba70dcd448 Mon Sep 17 00:00:00 2001 From: Pavel Zavora Date: Tue, 13 Sep 2022 09:33:04 +0200 Subject: [PATCH 4/6] chore: upgrade api-extractor and api-documenter --- package.json | 2 +- packages/apis/package.json | 2 +- packages/core/package.json | 2 +- packages/giraffe/package.json | 2 +- yarn.lock | 48 +++++++++++++++-------------------- 5 files changed, 25 insertions(+), 31 deletions(-) diff --git a/package.json b/package.json index 24168d685..1286904eb 100644 --- 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 index 3ad508961..625b6da07 100644 --- 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 index 91e2695cd..cf67010f1 100644 --- 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 index a9f29381e..d560f56e5 100644 --- 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/yarn.lock b/yarn.lock index b54980f15..2c49c47e6 100644 --- 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/rig-package@0.3.14": @@ -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" From e4d3b4f86bc5236a178f34891e44907858d29c63 Mon Sep 17 00:00:00 2001 From: Pavel Zavora Date: Tue, 13 Sep 2022 09:56:56 +0200 Subject: [PATCH 5/6] fix(docs): ignore reference check for symbol declaration, map specific references --- scripts/fix-extracted-api-files.js | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/scripts/fix-extracted-api-files.js b/scripts/fix-extracted-api-files.js index 2c271d26d..fa100b93b 100644 --- a/scripts/fix-extracted-api-files.js +++ b/scripts/fix-extracted-api-files.js @@ -9,7 +9,15 @@ 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) { @@ -57,17 +65,26 @@ function fixExtractedFile(file, json, errors = []) { 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} => ${replaced}`) - obj.canonicalReference = replaced + console.log(` FIXED ${canonicalReference} => ${mapped}`) + obj.canonicalReference = mapped return } - // report unresolved reference for (const ignoredPackage of ignoredReferencePackages) { if (canonicalReference.startsWith(ignoredPackage)) { return } } + // report unresolved references const msg = ` MISSING ${canonicalReference}` errors.push(`${file}: ${msg}`) console.log(msg) From 1a144ffa4542206ecc10c4296c3744b6dfc21a21 Mon Sep 17 00:00:00 2001 From: Pavel Zavora Date: Tue, 13 Sep 2022 10:04:46 +0200 Subject: [PATCH 6/6] chore: update changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 92a25ffa3..0baa96fa5 100644 --- 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