chore: add command to generate reference docs (#6506)

* chore: add command to generate reference docs

* chore: format

* chore: add comments and fix names

* chore: format

* chore:update patch for latest api documenter version

* chore: fix package-lock
This commit is contained in:
Maribeth Bottorff
2022-11-09 10:55:49 -08:00
committed by GitHub
parent 024e9c5cc6
commit 010a56bfad
5 changed files with 891 additions and 5 deletions

View File

@@ -19,6 +19,7 @@ const licenseTasks = require('./scripts/gulpfiles/license_tasks');
const appengineTasks = require('./scripts/gulpfiles/appengine_tasks');
const releaseTasks = require('./scripts/gulpfiles/release_tasks');
const cleanupTasks = require('./scripts/gulpfiles/cleanup_tasks');
const docsTasks = require('./scripts/gulpfiles/docs_tasks');
const testTasks = require('./scripts/gulpfiles/test_tasks');
module.exports = {
@@ -50,6 +51,7 @@ module.exports = {
testGenerators: testTasks.generators,
buildAdvancedCompilationTest: buildTasks.buildAdvancedCompilationTest,
gitCreateRC: gitTasks.createRC,
docs: docsTasks.docs,
// Targets intended only for invocation by scripts; may omit prerequisites.
onlyBuildAdvancedCompilationTest: buildTasks.onlyBuildAdvancedCompilationTest,

658
package-lock.json generated
View File

@@ -7,6 +7,7 @@
"": {
"name": "blockly",
"version": "9.0.1",
"hasInstallScript": true,
"license": "Apache-2.0",
"dependencies": {
"jsdom": "15.2.1"
@@ -16,6 +17,7 @@
"@blockly/dev-tools": "^5.0.0",
"@blockly/theme-modern": "^3.0.0",
"@hyperjump/json-schema": "^0.18.5",
"@microsoft/api-documenter": "^7.19.16",
"@microsoft/api-extractor": "^7.29.5",
"@typescript-eslint/eslint-plugin": "^5.33.1",
"@wdio/selenium-standalone-service": "^7.10.1",
@@ -32,6 +34,7 @@
"gulp-clang-format": "^1.0.27",
"gulp-concat": "^2.6.1",
"gulp-gzip": "^1.4.2",
"gulp-header": "^2.0.9",
"gulp-insert": "^0.5.0",
"gulp-rename": "^2.0.0",
"gulp-replace": "^1.0.0",
@@ -42,7 +45,9 @@
"http-server": "^14.0.0",
"js-green-licenses": "^3.0.0",
"json5": "^2.2.0",
"markdown-tables-to-json": "^0.1.7",
"mocha": "^10.0.0",
"patch-package": "^6.4.7",
"readline-sync": "^1.4.10",
"rimraf": "^3.0.2",
"selenium-standalone": "^8.0.3",
@@ -487,6 +492,87 @@
"integrity": "sha512-Q8206k8pTY7krW32cdmPsP+DqqLgWx/hYPSj9/+7SYqSqz7UuwPbfSe07lQtvuuaVyiSJveXk0E5RydOuWwsEg==",
"dev": true
},
"node_modules/@microsoft/api-documenter": {
"version": "7.19.24",
"resolved": "https://registry.npmjs.org/@microsoft/api-documenter/-/api-documenter-7.19.24.tgz",
"integrity": "sha512-XSjN07jsBusRDEqazbadGp6e0hds7GZGjdNGWmaQop32f7BxNv81NqE3H/OLONCZSklm/0fzJy8g14xZmByFtQ==",
"dev": true,
"dependencies": {
"@microsoft/api-extractor-model": "7.25.2",
"@microsoft/tsdoc": "0.14.2",
"@rushstack/node-core-library": "3.53.2",
"@rushstack/ts-command-line": "4.13.1",
"colors": "~1.2.1",
"js-yaml": "~3.13.1",
"resolve": "~1.17.0"
},
"bin": {
"api-documenter": "bin/api-documenter"
}
},
"node_modules/@microsoft/api-documenter/node_modules/@microsoft/api-extractor-model": {
"version": "7.25.2",
"resolved": "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.25.2.tgz",
"integrity": "sha512-+h1uCrLQXFAKMUdghhdDcnniDB+6UA/lS9ArlB4QZQ34UbLuXNy2oQ6fafFK8cKXU4mUPTF/yGRjv7JKD5L7eg==",
"dev": true,
"dependencies": {
"@microsoft/tsdoc": "0.14.2",
"@microsoft/tsdoc-config": "~0.16.1",
"@rushstack/node-core-library": "3.53.2"
}
},
"node_modules/@microsoft/api-documenter/node_modules/@microsoft/tsdoc": {
"version": "0.14.2",
"resolved": "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.14.2.tgz",
"integrity": "sha512-9b8mPpKrfeGRuhFH5iO1iwCLeIIsV6+H1sRfxbkoGXIyQE2BTsPd9zqSqQJ+pv5sJ/hT5M1zvOFL02MnEezFug==",
"dev": true
},
"node_modules/@microsoft/api-documenter/node_modules/@rushstack/ts-command-line": {
"version": "4.13.1",
"resolved": "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.13.1.tgz",
"integrity": "sha512-UTQMRyy/jH1IS2U+6pyzyn9xQ2iMcoUKkTcZUzOP/aaMiKlWLwCTDiBVwhw/M1crDx6apF9CwyjuWO9r1SBdJQ==",
"dev": true,
"dependencies": {
"@types/argparse": "1.0.38",
"argparse": "~1.0.9",
"colors": "~1.2.1",
"string-argv": "~0.3.1"
}
},
"node_modules/@microsoft/api-documenter/node_modules/argparse": {
"version": "1.0.10",
"resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
"integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
"dev": true,
"dependencies": {
"sprintf-js": "~1.0.2"
}
},
"node_modules/@microsoft/api-documenter/node_modules/js-yaml": {
"version": "3.13.1",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz",
"integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==",
"dev": true,
"dependencies": {
"argparse": "^1.0.7",
"esprima": "^4.0.0"
},
"bin": {
"js-yaml": "bin/js-yaml.js"
}
},
"node_modules/@microsoft/api-documenter/node_modules/resolve": {
"version": "1.17.0",
"resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz",
"integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==",
"dev": true,
"dependencies": {
"path-parse": "^1.0.6"
},
"funding": {
"url": "https://github.com/sponsors/ljharb"
}
},
"node_modules/@microsoft/api-extractor": {
"version": "7.33.4",
"resolved": "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.33.4.tgz",
@@ -782,6 +868,21 @@
"node": ">=10"
}
},
"node_modules/@ts-stack/markdown": {
"version": "1.4.0",
"resolved": "https://registry.npmjs.org/@ts-stack/markdown/-/markdown-1.4.0.tgz",
"integrity": "sha512-z3fkD8wGSyqTCp+axZVlr9hFKyM18XKPHEyC8vmohyTcqf5sRRy9Sd0omYBJ85IDW57DLEcfvVatXfUt1unEew==",
"dev": true,
"dependencies": {
"tslib": "^2.0.0"
}
},
"node_modules/@ts-stack/markdown/node_modules/tslib": {
"version": "2.4.1",
"resolved": "https://registry.npmjs.org/tslib/-/tslib-2.4.1.tgz",
"integrity": "sha512-tGyy4dAjRIEwI7BzsB0lynWgOpfqjUdq91XXAlIWD2OwKBH7oCl/GZG/HT4BOHrTlPMOASlMQ7veyTqpmRcrNA==",
"dev": true
},
"node_modules/@types/argparse": {
"version": "1.0.38",
"resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz",
@@ -1913,6 +2014,12 @@
"node": ">=12.0.0"
}
},
"node_modules/@yarnpkg/lockfile": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/@yarnpkg/lockfile/-/lockfile-1.1.0.tgz",
"integrity": "sha512-GpSwvyXOcOOlV70vbnzjj4fW5xW/FdUF6nQEt1ENy7m4ZCczi1+/buVUPAqmGfqznsORNFzUMjctTIp8a9tuCQ==",
"dev": true
},
"node_modules/abab": {
"version": "2.0.5",
"resolved": "https://registry.npmjs.org/abab/-/abab-2.0.5.tgz",
@@ -3174,6 +3281,12 @@
"node": ">=12.13.0"
}
},
"node_modules/ci-info": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/ci-info/-/ci-info-2.0.0.tgz",
"integrity": "sha512-5tK7EtrZ0N+OLFMthtqOj4fI2Jeb88C4CAZPu25LDVUgXJ0A3Js4PMGqrn0JU1W0Mh1/Z8wZzYPxqUrXeBboCQ==",
"dev": true
},
"node_modules/clang-format": {
"version": "1.8.0",
"resolved": "https://registry.npmjs.org/clang-format/-/clang-format-1.8.0.tgz",
@@ -5341,6 +5454,28 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/find-yarn-workspace-root": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/find-yarn-workspace-root/-/find-yarn-workspace-root-2.0.0.tgz",
"integrity": "sha512-1IMnbjt4KzsQfnhnzNd8wUEgXZ44IzZaZmnLYx7D5FZlaHt2gW20Cri8Q+E/t5tIj4+epTBub+2Zxu/vNILzqQ==",
"dev": true,
"dependencies": {
"micromatch": "^4.0.2"
}
},
"node_modules/find-yarn-workspace-root/node_modules/micromatch": {
"version": "4.0.5",
"resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz",
"integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==",
"dev": true,
"dependencies": {
"braces": "^3.0.2",
"picomatch": "^2.3.1"
},
"engines": {
"node": ">=8.6"
}
},
"node_modules/findup-sync": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/findup-sync/-/findup-sync-3.0.0.tgz",
@@ -6592,6 +6727,28 @@
"xtend": "~4.0.1"
}
},
"node_modules/gulp-header": {
"version": "2.0.9",
"resolved": "https://registry.npmjs.org/gulp-header/-/gulp-header-2.0.9.tgz",
"integrity": "sha512-LMGiBx+qH8giwrOuuZXSGvswcIUh0OiioNkUpLhNyvaC6/Ga8X6cfAeme2L5PqsbXMhL8o8b/OmVqIQdxprhcQ==",
"dev": true,
"dependencies": {
"concat-with-sourcemaps": "^1.1.0",
"lodash.template": "^4.5.0",
"map-stream": "0.0.7",
"through2": "^2.0.0"
}
},
"node_modules/gulp-header/node_modules/through2": {
"version": "2.0.5",
"resolved": "https://registry.npmjs.org/through2/-/through2-2.0.5.tgz",
"integrity": "sha512-/mrRod8xqpA+IHSLyGCQ2s8SPHiCDEeQJSep1jqLYeEUClOFG2Qsh+4FU6G9VeqpZnGW/Su8LQGc4YKni5rYSQ==",
"dev": true,
"dependencies": {
"readable-stream": "~2.3.6",
"xtend": "~4.0.1"
}
},
"node_modules/gulp-insert": {
"version": "0.5.0",
"resolved": "https://registry.npmjs.org/gulp-insert/-/gulp-insert-0.5.0.tgz",
@@ -7422,6 +7579,18 @@
"integrity": "sha512-NcdALwpXkTm5Zvvbk7owOUSvVvBKDgKP5/ewfXEznmQFfs4ZRmanOeKBTjRVjka3QFoN6XJ+9F3USqfHqTaU5w==",
"dev": true
},
"node_modules/is-ci": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/is-ci/-/is-ci-2.0.0.tgz",
"integrity": "sha512-YfJT7rkpQB0updsdHLGWrvhBJfcfzNNawYDNIyQXJz0IViGf75O8EBPKSdvw2rF+LGCsX4FZ8tcr3b19LcZq4w==",
"dev": true,
"dependencies": {
"ci-info": "^2.0.0"
},
"bin": {
"is-ci": "bin.js"
}
},
"node_modules/is-core-module": {
"version": "2.8.0",
"resolved": "https://registry.npmjs.org/is-core-module/-/is-core-module-2.8.0.tgz",
@@ -8102,6 +8271,15 @@
"node": ">=0.10.0"
}
},
"node_modules/klaw-sync": {
"version": "6.0.0",
"resolved": "https://registry.npmjs.org/klaw-sync/-/klaw-sync-6.0.0.tgz",
"integrity": "sha512-nIeuVSzdCCs6TDPTqI8w1Yre34sSq7AkZ4B3sfOBbI2CgVSB4Du4aLQijFU2+lhAFCwt9+42Hel6lQNIv6AntQ==",
"dev": true,
"dependencies": {
"graceful-fs": "^4.1.11"
}
},
"node_modules/ky": {
"version": "0.28.7",
"resolved": "https://registry.npmjs.org/ky/-/ky-0.28.7.tgz",
@@ -8629,6 +8807,15 @@
"node": ">=0.10.0"
}
},
"node_modules/markdown-tables-to-json": {
"version": "0.1.7",
"resolved": "https://registry.npmjs.org/markdown-tables-to-json/-/markdown-tables-to-json-0.1.7.tgz",
"integrity": "sha512-1kdyYY9vKqmcsPHe7pRbrIeoapik1MOAEYtqlFoz0zypBf7yrtt0gP1UHOlk5kLuZQL1qaWgk0zYtOd7eJB0yA==",
"dev": true,
"dependencies": {
"@ts-stack/markdown": "^1.3.0"
}
},
"node_modules/marky": {
"version": "1.2.2",
"resolved": "https://registry.npmjs.org/marky/-/marky-1.2.2.tgz",
@@ -9224,6 +9411,12 @@
"integrity": "sha1-yobR/ogoFpsBICCOPchCS524NCw=",
"dev": true
},
"node_modules/nice-try": {
"version": "1.0.5",
"resolved": "https://registry.npmjs.org/nice-try/-/nice-try-1.0.5.tgz",
"integrity": "sha512-1nh45deeb5olNY7eX82BkPO7SSxR5SSYJiPTrTdFUVYwAl8CKMA5N9PjTYkHiRjisVcxcQ1HXdLhx2qxxJzLNQ==",
"dev": true
},
"node_modules/nise": {
"version": "4.1.0",
"resolved": "https://registry.npmjs.org/nise/-/nise-4.1.0.tgz",
@@ -9666,7 +9859,6 @@
"resolved": "https://registry.npmjs.org/os-tmpdir/-/os-tmpdir-1.0.2.tgz",
"integrity": "sha1-u+Z0BseaqFxc/sdm/lc0VV36EnQ=",
"dev": true,
"peer": true,
"engines": {
"node": ">=0.10.0"
}
@@ -9979,6 +10171,155 @@
"node": ">=0.10.0"
}
},
"node_modules/patch-package": {
"version": "6.5.0",
"resolved": "https://registry.npmjs.org/patch-package/-/patch-package-6.5.0.tgz",
"integrity": "sha512-tC3EqJmo74yKqfsMzELaFwxOAu6FH6t+FzFOsnWAuARm7/n2xB5AOeOueE221eM9gtMuIKMKpF9tBy/X2mNP0Q==",
"dev": true,
"dependencies": {
"@yarnpkg/lockfile": "^1.1.0",
"chalk": "^4.1.2",
"cross-spawn": "^6.0.5",
"find-yarn-workspace-root": "^2.0.0",
"fs-extra": "^7.0.1",
"is-ci": "^2.0.0",
"klaw-sync": "^6.0.0",
"minimist": "^1.2.6",
"open": "^7.4.2",
"rimraf": "^2.6.3",
"semver": "^5.6.0",
"slash": "^2.0.0",
"tmp": "^0.0.33",
"yaml": "^1.10.2"
},
"bin": {
"patch-package": "index.js"
},
"engines": {
"node": ">=10",
"npm": ">5"
}
},
"node_modules/patch-package/node_modules/cross-spawn": {
"version": "6.0.5",
"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-6.0.5.tgz",
"integrity": "sha512-eTVLrBSt7fjbDygz805pMnstIs2VTBNkRm0qxZd+M7A5XDdxVRWO5MxGBXZhjY4cqLYLdtrGqRf8mBPmzwSpWQ==",
"dev": true,
"dependencies": {
"nice-try": "^1.0.4",
"path-key": "^2.0.1",
"semver": "^5.5.0",
"shebang-command": "^1.2.0",
"which": "^1.2.9"
},
"engines": {
"node": ">=4.8"
}
},
"node_modules/patch-package/node_modules/fs-extra": {
"version": "7.0.1",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz",
"integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==",
"dev": true,
"dependencies": {
"graceful-fs": "^4.1.2",
"jsonfile": "^4.0.0",
"universalify": "^0.1.0"
},
"engines": {
"node": ">=6 <7 || >=8"
}
},
"node_modules/patch-package/node_modules/jsonfile": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz",
"integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==",
"dev": true,
"optionalDependencies": {
"graceful-fs": "^4.1.6"
}
},
"node_modules/patch-package/node_modules/path-key": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/path-key/-/path-key-2.0.1.tgz",
"integrity": "sha512-fEHGKCSmUSDPv4uoj8AlD+joPlq3peND+HRYyxFz4KPw4z926S/b8rIuFs2FYJg3BwsxJf6A9/3eIdLaYC+9Dw==",
"dev": true,
"engines": {
"node": ">=4"
}
},
"node_modules/patch-package/node_modules/rimraf": {
"version": "2.7.1",
"resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.7.1.tgz",
"integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==",
"dev": true,
"dependencies": {
"glob": "^7.1.3"
},
"bin": {
"rimraf": "bin.js"
}
},
"node_modules/patch-package/node_modules/semver": {
"version": "5.7.1",
"resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz",
"integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==",
"dev": true,
"bin": {
"semver": "bin/semver"
}
},
"node_modules/patch-package/node_modules/shebang-command": {
"version": "1.2.0",
"resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-1.2.0.tgz",
"integrity": "sha512-EV3L1+UQWGor21OmnvojK36mhg+TyIKDh3iFBKBohr5xeXIhNBcx8oWdgkTEEQ+BEFFYdLRuqMfd5L84N1V5Vg==",
"dev": true,
"dependencies": {
"shebang-regex": "^1.0.0"
},
"engines": {
"node": ">=0.10.0"
}
},
"node_modules/patch-package/node_modules/shebang-regex": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-1.0.0.tgz",
"integrity": "sha512-wpoSFAxys6b2a2wHZ1XpDSgD7N9iVjg29Ph9uV/uaP9Ex/KXlkTZTeddxDPSYQpgvzKLGJke2UU0AzoGCjNIvQ==",
"dev": true,
"engines": {
"node": ">=0.10.0"
}
},
"node_modules/patch-package/node_modules/slash": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/slash/-/slash-2.0.0.tgz",
"integrity": "sha512-ZYKh3Wh2z1PpEXWr0MpSBZ0V6mZHAQfYevttO11c51CaWjGTaadiKZ+wVt1PbMlDV5qhMFslpZCemhwOK7C89A==",
"dev": true,
"engines": {
"node": ">=6"
}
},
"node_modules/patch-package/node_modules/universalify": {
"version": "0.1.2",
"resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz",
"integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==",
"dev": true,
"engines": {
"node": ">= 4.0.0"
}
},
"node_modules/patch-package/node_modules/which": {
"version": "1.3.1",
"resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz",
"integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==",
"dev": true,
"dependencies": {
"isexe": "^2.0.0"
},
"bin": {
"which": "bin/which"
}
},
"node_modules/path-dirname": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/path-dirname/-/path-dirname-1.0.2.tgz",
@@ -12336,7 +12677,6 @@
"resolved": "https://registry.npmjs.org/tmp/-/tmp-0.0.33.tgz",
"integrity": "sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw==",
"dev": true,
"peer": true,
"dependencies": {
"os-tmpdir": "~1.0.2"
},
@@ -13499,6 +13839,15 @@
"integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
"dev": true
},
"node_modules/yaml": {
"version": "1.10.2",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",
"integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==",
"dev": true,
"engines": {
"node": ">= 6"
}
},
"node_modules/yargs": {
"version": "17.6.0",
"resolved": "https://registry.npmjs.org/yargs/-/yargs-17.6.0.tgz",
@@ -14113,6 +14462,80 @@
}
}
},
"@microsoft/api-documenter": {
"version": "7.19.24",
"resolved": "https://registry.npmjs.org/@microsoft/api-documenter/-/api-documenter-7.19.24.tgz",
"integrity": "sha512-XSjN07jsBusRDEqazbadGp6e0hds7GZGjdNGWmaQop32f7BxNv81NqE3H/OLONCZSklm/0fzJy8g14xZmByFtQ==",
"dev": true,
"requires": {
"@microsoft/api-extractor-model": "7.25.2",
"@microsoft/tsdoc": "0.14.2",
"@rushstack/node-core-library": "3.53.2",
"@rushstack/ts-command-line": "4.13.1",
"colors": "~1.2.1",
"js-yaml": "~3.13.1",
"resolve": "~1.17.0"
},
"dependencies": {
"@microsoft/api-extractor-model": {
"version": "7.25.2",
"resolved": "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.25.2.tgz",
"integrity": "sha512-+h1uCrLQXFAKMUdghhdDcnniDB+6UA/lS9ArlB4QZQ34UbLuXNy2oQ6fafFK8cKXU4mUPTF/yGRjv7JKD5L7eg==",
"dev": true,
"requires": {
"@microsoft/tsdoc": "0.14.2",
"@microsoft/tsdoc-config": "~0.16.1",
"@rushstack/node-core-library": "3.53.2"
}
},
"@microsoft/tsdoc": {
"version": "0.14.2",
"resolved": "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.14.2.tgz",
"integrity": "sha512-9b8mPpKrfeGRuhFH5iO1iwCLeIIsV6+H1sRfxbkoGXIyQE2BTsPd9zqSqQJ+pv5sJ/hT5M1zvOFL02MnEezFug==",
"dev": true
},
"@rushstack/ts-command-line": {
"version": "4.13.1",
"resolved": "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.13.1.tgz",
"integrity": "sha512-UTQMRyy/jH1IS2U+6pyzyn9xQ2iMcoUKkTcZUzOP/aaMiKlWLwCTDiBVwhw/M1crDx6apF9CwyjuWO9r1SBdJQ==",
"dev": true,
"requires": {
"@types/argparse": "1.0.38",
"argparse": "~1.0.9",
"colors": "~1.2.1",
"string-argv": "~0.3.1"
}
},
"argparse": {
"version": "1.0.10",
"resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
"integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
"dev": true,
"requires": {
"sprintf-js": "~1.0.2"
}
},
"js-yaml": {
"version": "3.13.1",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz",
"integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==",
"dev": true,
"requires": {
"argparse": "^1.0.7",
"esprima": "^4.0.0"
}
},
"resolve": {
"version": "1.17.0",
"resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz",
"integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==",
"dev": true,
"requires": {
"path-parse": "^1.0.6"
}
}
}
},
"@microsoft/api-extractor": {
"version": "7.33.4",
"resolved": "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.33.4.tgz",
@@ -14376,6 +14799,23 @@
"defer-to-connect": "^2.0.0"
}
},
"@ts-stack/markdown": {
"version": "1.4.0",
"resolved": "https://registry.npmjs.org/@ts-stack/markdown/-/markdown-1.4.0.tgz",
"integrity": "sha512-z3fkD8wGSyqTCp+axZVlr9hFKyM18XKPHEyC8vmohyTcqf5sRRy9Sd0omYBJ85IDW57DLEcfvVatXfUt1unEew==",
"dev": true,
"requires": {
"tslib": "^2.0.0"
},
"dependencies": {
"tslib": {
"version": "2.4.1",
"resolved": "https://registry.npmjs.org/tslib/-/tslib-2.4.1.tgz",
"integrity": "sha512-tGyy4dAjRIEwI7BzsB0lynWgOpfqjUdq91XXAlIWD2OwKBH7oCl/GZG/HT4BOHrTlPMOASlMQ7veyTqpmRcrNA==",
"dev": true
}
}
},
"@types/argparse": {
"version": "1.0.38",
"resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz",
@@ -15230,6 +15670,12 @@
"p-iteration": "^1.1.8"
}
},
"@yarnpkg/lockfile": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/@yarnpkg/lockfile/-/lockfile-1.1.0.tgz",
"integrity": "sha512-GpSwvyXOcOOlV70vbnzjj4fW5xW/FdUF6nQEt1ENy7m4ZCczi1+/buVUPAqmGfqznsORNFzUMjctTIp8a9tuCQ==",
"dev": true
},
"abab": {
"version": "2.0.5",
"resolved": "https://registry.npmjs.org/abab/-/abab-2.0.5.tgz",
@@ -16186,6 +16632,12 @@
"lighthouse-logger": "^1.0.0"
}
},
"ci-info": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/ci-info/-/ci-info-2.0.0.tgz",
"integrity": "sha512-5tK7EtrZ0N+OLFMthtqOj4fI2Jeb88C4CAZPu25LDVUgXJ0A3Js4PMGqrn0JU1W0Mh1/Z8wZzYPxqUrXeBboCQ==",
"dev": true
},
"clang-format": {
"version": "1.8.0",
"resolved": "https://registry.npmjs.org/clang-format/-/clang-format-1.8.0.tgz",
@@ -17931,6 +18383,27 @@
"path-exists": "^4.0.0"
}
},
"find-yarn-workspace-root": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/find-yarn-workspace-root/-/find-yarn-workspace-root-2.0.0.tgz",
"integrity": "sha512-1IMnbjt4KzsQfnhnzNd8wUEgXZ44IzZaZmnLYx7D5FZlaHt2gW20Cri8Q+E/t5tIj4+epTBub+2Zxu/vNILzqQ==",
"dev": true,
"requires": {
"micromatch": "^4.0.2"
},
"dependencies": {
"micromatch": {
"version": "4.0.5",
"resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz",
"integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==",
"dev": true,
"requires": {
"braces": "^3.0.2",
"picomatch": "^2.3.1"
}
}
}
},
"findup-sync": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/findup-sync/-/findup-sync-3.0.0.tgz",
@@ -18931,6 +19404,30 @@
}
}
},
"gulp-header": {
"version": "2.0.9",
"resolved": "https://registry.npmjs.org/gulp-header/-/gulp-header-2.0.9.tgz",
"integrity": "sha512-LMGiBx+qH8giwrOuuZXSGvswcIUh0OiioNkUpLhNyvaC6/Ga8X6cfAeme2L5PqsbXMhL8o8b/OmVqIQdxprhcQ==",
"dev": true,
"requires": {
"concat-with-sourcemaps": "^1.1.0",
"lodash.template": "^4.5.0",
"map-stream": "0.0.7",
"through2": "^2.0.0"
},
"dependencies": {
"through2": {
"version": "2.0.5",
"resolved": "https://registry.npmjs.org/through2/-/through2-2.0.5.tgz",
"integrity": "sha512-/mrRod8xqpA+IHSLyGCQ2s8SPHiCDEeQJSep1jqLYeEUClOFG2Qsh+4FU6G9VeqpZnGW/Su8LQGc4YKni5rYSQ==",
"dev": true,
"requires": {
"readable-stream": "~2.3.6",
"xtend": "~4.0.1"
}
}
}
},
"gulp-insert": {
"version": "0.5.0",
"resolved": "https://registry.npmjs.org/gulp-insert/-/gulp-insert-0.5.0.tgz",
@@ -19595,6 +20092,15 @@
"integrity": "sha512-NcdALwpXkTm5Zvvbk7owOUSvVvBKDgKP5/ewfXEznmQFfs4ZRmanOeKBTjRVjka3QFoN6XJ+9F3USqfHqTaU5w==",
"dev": true
},
"is-ci": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/is-ci/-/is-ci-2.0.0.tgz",
"integrity": "sha512-YfJT7rkpQB0updsdHLGWrvhBJfcfzNNawYDNIyQXJz0IViGf75O8EBPKSdvw2rF+LGCsX4FZ8tcr3b19LcZq4w==",
"dev": true,
"requires": {
"ci-info": "^2.0.0"
}
},
"is-core-module": {
"version": "2.8.0",
"resolved": "https://registry.npmjs.org/is-core-module/-/is-core-module-2.8.0.tgz",
@@ -20127,6 +20633,15 @@
"integrity": "sha512-NGEErnH6F2vUuXDh+OlbcKW7/wOcfdRHaZ7VWtqCztfHri/++YKmP51OdWeGPuqCOba6kk2OTe5d02VmTB80Pw==",
"dev": true
},
"klaw-sync": {
"version": "6.0.0",
"resolved": "https://registry.npmjs.org/klaw-sync/-/klaw-sync-6.0.0.tgz",
"integrity": "sha512-nIeuVSzdCCs6TDPTqI8w1Yre34sSq7AkZ4B3sfOBbI2CgVSB4Du4aLQijFU2+lhAFCwt9+42Hel6lQNIv6AntQ==",
"dev": true,
"requires": {
"graceful-fs": "^4.1.11"
}
},
"ky": {
"version": "0.28.7",
"resolved": "https://registry.npmjs.org/ky/-/ky-0.28.7.tgz",
@@ -20586,6 +21101,15 @@
"object-visit": "^1.0.0"
}
},
"markdown-tables-to-json": {
"version": "0.1.7",
"resolved": "https://registry.npmjs.org/markdown-tables-to-json/-/markdown-tables-to-json-0.1.7.tgz",
"integrity": "sha512-1kdyYY9vKqmcsPHe7pRbrIeoapik1MOAEYtqlFoz0zypBf7yrtt0gP1UHOlk5kLuZQL1qaWgk0zYtOd7eJB0yA==",
"dev": true,
"requires": {
"@ts-stack/markdown": "^1.3.0"
}
},
"marky": {
"version": "1.2.2",
"resolved": "https://registry.npmjs.org/marky/-/marky-1.2.2.tgz",
@@ -21065,6 +21589,12 @@
"integrity": "sha1-yobR/ogoFpsBICCOPchCS524NCw=",
"dev": true
},
"nice-try": {
"version": "1.0.5",
"resolved": "https://registry.npmjs.org/nice-try/-/nice-try-1.0.5.tgz",
"integrity": "sha512-1nh45deeb5olNY7eX82BkPO7SSxR5SSYJiPTrTdFUVYwAl8CKMA5N9PjTYkHiRjisVcxcQ1HXdLhx2qxxJzLNQ==",
"dev": true
},
"nise": {
"version": "4.1.0",
"resolved": "https://registry.npmjs.org/nise/-/nise-4.1.0.tgz",
@@ -21402,8 +21932,7 @@
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/os-tmpdir/-/os-tmpdir-1.0.2.tgz",
"integrity": "sha1-u+Z0BseaqFxc/sdm/lc0VV36EnQ=",
"dev": true,
"peer": true
"dev": true
},
"p-cancelable": {
"version": "2.1.1",
@@ -21641,6 +22170,120 @@
"integrity": "sha1-s2PlXoAGym/iF4TS2yK9FdeRfxQ=",
"dev": true
},
"patch-package": {
"version": "6.5.0",
"resolved": "https://registry.npmjs.org/patch-package/-/patch-package-6.5.0.tgz",
"integrity": "sha512-tC3EqJmo74yKqfsMzELaFwxOAu6FH6t+FzFOsnWAuARm7/n2xB5AOeOueE221eM9gtMuIKMKpF9tBy/X2mNP0Q==",
"dev": true,
"requires": {
"@yarnpkg/lockfile": "^1.1.0",
"chalk": "^4.1.2",
"cross-spawn": "^6.0.5",
"find-yarn-workspace-root": "^2.0.0",
"fs-extra": "^7.0.1",
"is-ci": "^2.0.0",
"klaw-sync": "^6.0.0",
"minimist": "^1.2.6",
"open": "^7.4.2",
"rimraf": "^2.6.3",
"semver": "^5.6.0",
"slash": "^2.0.0",
"tmp": "^0.0.33",
"yaml": "^1.10.2"
},
"dependencies": {
"cross-spawn": {
"version": "6.0.5",
"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-6.0.5.tgz",
"integrity": "sha512-eTVLrBSt7fjbDygz805pMnstIs2VTBNkRm0qxZd+M7A5XDdxVRWO5MxGBXZhjY4cqLYLdtrGqRf8mBPmzwSpWQ==",
"dev": true,
"requires": {
"nice-try": "^1.0.4",
"path-key": "^2.0.1",
"semver": "^5.5.0",
"shebang-command": "^1.2.0",
"which": "^1.2.9"
}
},
"fs-extra": {
"version": "7.0.1",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz",
"integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==",
"dev": true,
"requires": {
"graceful-fs": "^4.1.2",
"jsonfile": "^4.0.0",
"universalify": "^0.1.0"
}
},
"jsonfile": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz",
"integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==",
"dev": true,
"requires": {
"graceful-fs": "^4.1.6"
}
},
"path-key": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/path-key/-/path-key-2.0.1.tgz",
"integrity": "sha512-fEHGKCSmUSDPv4uoj8AlD+joPlq3peND+HRYyxFz4KPw4z926S/b8rIuFs2FYJg3BwsxJf6A9/3eIdLaYC+9Dw==",
"dev": true
},
"rimraf": {
"version": "2.7.1",
"resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.7.1.tgz",
"integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==",
"dev": true,
"requires": {
"glob": "^7.1.3"
}
},
"semver": {
"version": "5.7.1",
"resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz",
"integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==",
"dev": true
},
"shebang-command": {
"version": "1.2.0",
"resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-1.2.0.tgz",
"integrity": "sha512-EV3L1+UQWGor21OmnvojK36mhg+TyIKDh3iFBKBohr5xeXIhNBcx8oWdgkTEEQ+BEFFYdLRuqMfd5L84N1V5Vg==",
"dev": true,
"requires": {
"shebang-regex": "^1.0.0"
}
},
"shebang-regex": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-1.0.0.tgz",
"integrity": "sha512-wpoSFAxys6b2a2wHZ1XpDSgD7N9iVjg29Ph9uV/uaP9Ex/KXlkTZTeddxDPSYQpgvzKLGJke2UU0AzoGCjNIvQ==",
"dev": true
},
"slash": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/slash/-/slash-2.0.0.tgz",
"integrity": "sha512-ZYKh3Wh2z1PpEXWr0MpSBZ0V6mZHAQfYevttO11c51CaWjGTaadiKZ+wVt1PbMlDV5qhMFslpZCemhwOK7C89A==",
"dev": true
},
"universalify": {
"version": "0.1.2",
"resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz",
"integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==",
"dev": true
},
"which": {
"version": "1.3.1",
"resolved": "https://registry.npmjs.org/which/-/which-1.3.1.tgz",
"integrity": "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==",
"dev": true,
"requires": {
"isexe": "^2.0.0"
}
}
}
},
"path-dirname": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/path-dirname/-/path-dirname-1.0.2.tgz",
@@ -23553,7 +24196,6 @@
"resolved": "https://registry.npmjs.org/tmp/-/tmp-0.0.33.tgz",
"integrity": "sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw==",
"dev": true,
"peer": true,
"requires": {
"os-tmpdir": "~1.0.2"
}
@@ -24475,6 +25117,12 @@
"integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
"dev": true
},
"yaml": {
"version": "1.10.2",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",
"integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==",
"dev": true
},
"yargs": {
"version": "17.6.0",
"resolved": "https://registry.npmjs.org/yargs/-/yargs-17.6.0.tgz",

View File

@@ -32,6 +32,7 @@
"deployDemos": "npm ci && gulp deployDemos",
"deployDemos:beta": "npm ci && gulp deployDemosBeta",
"deps": "gulp deps",
"docs": "gulp docs",
"format": "gulp format",
"format:sortrequires": "gulp sortRequires",
"generate:langfiles": "exit 1 # Deprecated; use \"npm run messages\" instead.",
@@ -43,6 +44,7 @@
"minify": "gulp minify",
"only:compile:advanced": "gulp onlyBuildAdvancedCompilationTest --debug",
"package": "gulp package",
"postinstall": "patch-package",
"prepare": "gulp prepare",
"prepareDemos": "gulp prepareDemos",
"publish": "npm ci && gulp publish",
@@ -72,6 +74,7 @@
"@blockly/dev-tools": "^5.0.0",
"@blockly/theme-modern": "^3.0.0",
"@hyperjump/json-schema": "^0.18.5",
"@microsoft/api-documenter": "^7.19.16",
"@microsoft/api-extractor": "^7.29.5",
"@typescript-eslint/eslint-plugin": "^5.33.1",
"@wdio/selenium-standalone-service": "^7.10.1",
@@ -87,6 +90,7 @@
"gulp": "^4.0.2",
"gulp-clang-format": "^1.0.27",
"gulp-concat": "^2.6.1",
"gulp-header": "^2.0.9",
"gulp-gzip": "^1.4.2",
"gulp-insert": "^0.5.0",
"gulp-rename": "^2.0.0",
@@ -98,7 +102,9 @@
"http-server": "^14.0.0",
"js-green-licenses": "^3.0.0",
"json5": "^2.2.0",
"markdown-tables-to-json": "^0.1.7",
"mocha": "^10.0.0",
"patch-package": "^6.4.7",
"readline-sync": "^1.4.10",
"rimraf": "^3.0.2",
"selenium-standalone": "^8.0.3",

View File

@@ -0,0 +1,87 @@
diff --git a/node_modules/@microsoft/api-documenter/lib/documenters/MarkdownDocumenter.js b/node_modules/@microsoft/api-documenter/lib/documenters/MarkdownDocumenter.js
index 421f89f..b9d329b 100644
--- a/node_modules/@microsoft/api-documenter/lib/documenters/MarkdownDocumenter.js
+++ b/node_modules/@microsoft/api-documenter/lib/documenters/MarkdownDocumenter.js
@@ -856,12 +856,15 @@ class MarkdownDocumenter {
}
_writeBreadcrumb(output, apiItem) {
const configuration = this._tsdocConfiguration;
- output.appendNodeInParagraph(new tsdoc_1.DocLinkTag({
- configuration,
- tagName: '@link',
- linkText: 'Home',
- urlDestination: this._getLinkFilenameForApiItem(this._apiModel)
- }));
+ // Don't print the first breadcrumb, because there's only one package, so we don't need the Home link.
+ // output.appendNodeInParagraph(new tsdoc_1.DocLinkTag({
+ // configuration,
+ // tagName: '@link',
+ // linkText: 'Home',
+ // urlDestination: this._getLinkFilenameForApiItem(this._apiModel)
+ // }));
+
+ let first = true;
for (const hierarchyItem of apiItem.getHierarchy()) {
switch (hierarchyItem.kind) {
case api_extractor_model_1.ApiItemKind.Model:
@@ -871,18 +874,24 @@ class MarkdownDocumenter {
// this may change in the future.
break;
default:
- output.appendNodesInParagraph([
- new tsdoc_1.DocPlainText({
- configuration,
- text: ' > '
- }),
+ // Only print the breadcrumb separator if it's not the first item we're printing.
+ if (!first) {
+ output.appendNodeInParagraph(
+ new tsdoc_1.DocPlainText({
+ configuration,
+ text: ' > '
+ })
+ );
+ }
+ first = false;
+ output.appendNodeInParagraph(
new tsdoc_1.DocLinkTag({
configuration,
tagName: '@link',
linkText: hierarchyItem.displayName,
urlDestination: this._getLinkFilenameForApiItem(hierarchyItem)
})
- ]);
+ );
}
}
}
@@ -947,11 +956,13 @@ class MarkdownDocumenter {
// For overloaded methods, add a suffix such as "MyClass.myMethod_2".
let qualifiedName = Utilities_1.Utilities.getSafeFilenameForName(hierarchyItem.displayName);
if (api_extractor_model_1.ApiParameterListMixin.isBaseClassOf(hierarchyItem)) {
- if (hierarchyItem.overloadIndex > 1) {
- // Subtract one for compatibility with earlier releases of API Documenter.
- // (This will get revamped when we fix GitHub issue #1308)
- qualifiedName += `_${hierarchyItem.overloadIndex - 1}`;
- }
+ // https://github.com/microsoft/rushstack/issues/1921
+ // if (hierarchyItem.overloadIndex > 1) {
+ // // Subtract one for compatibility with earlier releases of API Documenter.
+ // // (This will get revamped when we fix GitHub issue #1308)
+ // qualifiedName += `_${hierarchyItem.overloadIndex - 1}`;
+ // }
+ qualifiedName += `_${hierarchyItem.overloadIndex}`;
}
switch (hierarchyItem.kind) {
case api_extractor_model_1.ApiItemKind.Model:
@@ -962,7 +973,9 @@ class MarkdownDocumenter {
baseName = Utilities_1.Utilities.getSafeFilenameForName(node_core_library_1.PackageName.getUnscopedName(hierarchyItem.displayName));
break;
default:
- baseName += '.' + qualifiedName;
+ // https://github.com/microsoft/rushstack/issues/1921
+ // baseName += '.' + qualifiedName;
+ baseName += '.' + qualifiedName + '_' + hierarchyItem.kind.toLowerCase();
}
}
return baseName + '.md';

View File

@@ -0,0 +1,143 @@
const {execSync} = require('child_process');
const {Extractor} = require('markdown-tables-to-json');
const fs = require('fs');
const gulp = require('gulp');
const header = require('gulp-header');
const replace = require('gulp-replace');
const DOCS_DIR = 'docs';
/**
* Run API Extractor to generate the intermediate json file.
*/
const generateApiJson = function(done) {
execSync('api-extractor run --local', {stdio: 'inherit'});
done();
}
/**
* API Extractor output spuriously renames some functions. Undo that.
* See https://github.com/microsoft/rushstack/issues/2534
*/
const removeRenames = function() {
return gulp.src('temp/blockly.api.json')
.pipe(replace('_2', ''))
.pipe(gulp.dest('temp/'));
}
/**
* Run API Documenter to generate the raw docs files.
*/
const generateDocs = function(done) {
if (!fs.existsSync(DOCS_DIR)) {
// Create the directory if it doesn't exist.
// If it already exists, the contents will be deleted by api-documenter.
fs.mkdirSync(DOCS_DIR);
}
execSync(
`api-documenter markdown --input-folder temp --output-folder ${DOCS_DIR}`,
{stdio: 'inherit'});
done();
}
/**
* Prepends the project and book metadata that devsite requires.
*/
const prependBook = function() {
return gulp.src('docs/*.md')
.pipe(header(
'Project: /blockly/_project.yaml\nBook: /blockly/_book.yaml\n\n'))
.pipe(gulp.dest(DOCS_DIR));
}
/**
* Creates a map of top-level pages to sub-pages, e.g. a mapping
* of `block_class` to every page associated with that class.
* This is needed to create an accurate table of contents.
* @param {string[]} allFiles All files in docs directory.
* @returns {Map<string, string[]>}
*/
const buildAlternatePathsMap = function(allFiles) {
let map = new Map();
for (let file of allFiles) {
// Get the name of the class/namespaces/variable/etc., i.e. the top-level
// page.
let filePieces = file.split('.');
let name = filePieces[1];
if (!map.has(name)) {
map.set(name, []);
}
if (filePieces[2] === 'md') {
// Don't add the top-level page to the map.
continue;
}
// Add all sub-pages to the array for the corresponding top-level page.
map.get(name).push(file);
}
return map;
}
/**
* Create the _toc.yaml file used by devsite to create the leftnav.
* This file is generated from the contents of `blockly.md` which contains links
* to the other top-level API pages (each class, namespace, etc.).
*
* The `alternate_paths` for each top-level page contains the path for
* each associated sub-page. All subpages must be linked to their top-level page
* in the TOC for the left nav bar to remain correct after drilling down into a
* sub-page.
*/
const createToc = function(done) {
const fileContent = fs.readFileSync(`${DOCS_DIR}/blockly.md`, 'utf8');
// Create the TOC file. The file should not yet exist; if it does, this
// operation will fail.
const toc = fs.openSync(`${DOCS_DIR}/_toc.yaml`, 'ax');
const files = fs.readdirSync(DOCS_DIR);
const map = buildAlternatePathsMap(files);
const referencePath = '/blockly/reference/js';
fs.writeSync(toc, 'toc:\n');
// Generate a section of TOC for each section/heading in the overview file.
const sections = fileContent.split('##');
for (let section of sections) {
// This converts the md table in each section to a JS object
const table = Extractor.extractObject(section, 'rows', false);
if (!table) {
continue;
}
// Get the name of the section, i.e. the text immediately after the `##` in
// the source doc
const sectionName = section.split('\n')[0].trim();
fs.writeSync(toc, `- heading: ${sectionName}\n`);
for (let row in table) {
// After going through the Extractor, the markdown is now HTML.
// Each row in the table is now a link (anchor tag).
// Get the target of the link, excluding the first `.` since we don't want
// a relative path.
const path = /href="\.(.*?)"/.exec(row)?.[1];
// Get the name of the link (text in between the <a> and </a>)
const name = /">(.*?)</.exec(row)?.[1];
if (!path || !name) {
continue;
}
fs.writeSync(toc, `- title: ${name}\n path: ${referencePath}${path}\n`);
// Get the list of sub-pages for this page.
// Add each sub-page to the `alternate_paths` property.
let pages = map.get(path.split('.')[1]);
if (pages?.length) {
fs.writeSync(toc, ` alternate_paths:\n`);
for (let page of pages) {
fs.writeSync(toc, ` - ${referencePath}/${page}\n`);
}
}
}
}
done();
}
const docs = gulp.series(
generateApiJson, removeRenames, generateDocs,
gulp.parallel(prependBook, createToc));
module.exports = {docs};