diff --git a/gulpfile.js b/gulpfile.js index 8c15e5a66..9ac75c91a 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -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, diff --git a/package-lock.json b/package-lock.json index 89e407167..d8c7e4b14 100644 --- a/package-lock.json +++ b/package-lock.json @@ -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", diff --git a/package.json b/package.json index 5d7137ebb..36f2c88a5 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/patches/@microsoft+api-documenter+7.19.24.patch b/patches/@microsoft+api-documenter+7.19.24.patch new file mode 100644 index 000000000..9b11e786a --- /dev/null +++ b/patches/@microsoft+api-documenter+7.19.24.patch @@ -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'; diff --git a/scripts/gulpfiles/docs_tasks.js b/scripts/gulpfiles/docs_tasks.js new file mode 100644 index 000000000..8885af24a --- /dev/null +++ b/scripts/gulpfiles/docs_tasks.js @@ -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} + */ +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 and ) + const name = /">(.*?)