[Docs] Adding docs npm script (#12941)

This newly added command `docs` can help increase the quality of our documentation comments. It enables us to have a tight feedback loop on what is being generated as a documentation of our packages. I am pinning `typedoc` to v0.15.0 for now because this is the version being used for generating docs at `docs.microsoft.com`. This version should be updated when that team updates theirs. Fixes #12928
Azure · Dec 17, 2020 · 7e0bd75 · 7e0bd75
1 parent 5b0fe95
commit 7e0bd75
Show file tree

Hide file tree

Showing 57 changed files with 337 additions and 170 deletions.
diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml
diff --git a/common/tools/dev-tool/package.json b/common/tools/dev-tool/package.json
@@ -21,7 +21,8 @@
     "pack": "npm pack 2>&1",
     "prebuild": "npm run clean",
     "unit-test": "mocha --require ts-node/register test/**/*.spec.ts",
-    "build:samples": "echo Skipped."
+    "build:samples": "echo Skipped.",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "repository": "github:Azure/azure-sdk-for-js",
   "author": "Microsoft Corporation",
@@ -63,6 +64,7 @@
     "rimraf": "^3.0.0",
     "rollup": "^1.16.3",
     "rollup-plugin-sourcemaps": "^0.4.2",
-    "rollup-plugin-visualizer": "^4.0.4"
+    "rollup-plugin-visualizer": "^4.0.4",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/common/tools/eslint-plugin-azure-sdk/package.json b/common/tools/eslint-plugin-azure-sdk/package.json
@@ -51,7 +51,8 @@
     "unit-test:node": "mocha --require source-map-support/register --timeout 10000 --full-trace --recursive dist/tests",
     "unit-test:browser": "echo skipped",
     "unit-test": "npm run unit-test:node && npm run unit-test:browser",
-    "test": "npm run clean && npm run build:test && npm run unit-test"
+    "test": "npm run clean && npm run build:test && npm run unit-test",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "engines": {
     "node": ">=8.0.0"
@@ -89,6 +90,7 @@
     "rimraf": "^3.0.0",
     "source-map-support": "^0.5.9",
     "mocha-junit-reporter": "^1.18.0",
-    "typescript": "4.1.2"
+    "typescript": "4.1.2",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/anomalydetector/ai-anomaly-detector/package.json b/sdk/anomalydetector/ai-anomaly-detector/package.json
@@ -33,7 +33,8 @@
     "test": "npm run build:test && npm run unit-test && npm run integration-test",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "mocha --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --timeout 1200000 --full-trace dist-test/index.node.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -110,7 +111,8 @@
     "rollup-plugin-visualizer": "^4.0.4",
     "typescript": "4.1.2",
     "util": "^0.12.1",
-    "@azure/test-utils-recorder": "^1.0.0"
+    "@azure/test-utils-recorder": "^1.0.0",
+    "typedoc": "0.15.0"
   },
   "//smokeTestConfiguration": {
     "skipFolder": true

diff --git a/sdk/appconfiguration/app-configuration/package.json b/sdk/appconfiguration/app-configuration/package.json
@@ -67,7 +67,8 @@
     "test": "npm run clean && npm run build:test && npm run unit-test",
     "unit-test:browser": "",
     "unit-test:node": "mocha --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --timeout 180000 --full-trace test-dist/index.node.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "sideEffects": false,
   "autoPublish": false,
@@ -133,6 +134,7 @@
     "ts-node": "^8.3.0",
     "typescript": "4.1.2",
     "uglify-js": "^3.4.9",
-    "cross-env": "^7.0.2"
+    "cross-env": "^7.0.2",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/communication/communication-administration/package.json b/sdk/communication/communication-administration/package.json
@@ -38,7 +38,8 @@
     "test:watch": "npm run test -- --watch --reporter min",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "mocha --reporter ../../../common/tools/mocha-multi-reporter.js dist-test/index.node.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -119,6 +120,7 @@
     "rollup-plugin-shim": "^1.0.0",
     "rollup": "^1.16.3",
     "sinon": "^9.0.2",
-    "typescript": "4.1.2"
+    "typescript": "4.1.2",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/communication/communication-chat/package.json b/sdk/communication/communication-chat/package.json
@@ -31,7 +31,8 @@
     "test": "npm run build:test && npm run unit-test && npm run integration-test",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "mocha --reporter ../../../common/tools/mocha-multi-reporter.js dist-test/index.node.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -121,6 +122,7 @@
     "rollup": "^1.16.3",
     "sinon": "^9.0.2",
     "typescript": "4.1.2",
-    "util": "^0.12.1"
+    "util": "^0.12.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/communication/communication-common/package.json b/sdk/communication/communication-common/package.json
@@ -33,7 +33,8 @@
     "test": "npm run build:test && npm run unit-test && npm run integration-test",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "mocha --reporter ../../../common/tools/mocha-multi-reporter.js dist-test/index.node.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -112,6 +113,7 @@
     "rollup": "^1.16.3",
     "sinon": "^9.0.2",
     "typescript": "4.1.2",
-    "util": "^0.12.1"
+    "util": "^0.12.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/communication/communication-sms/package.json b/sdk/communication/communication-sms/package.json
@@ -37,7 +37,8 @@
     "test": "npm run build:test && npm run unit-test && npm run integration-test",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "mocha --reporter ../../../common/tools/mocha-multi-reporter.js dist-test/index.node.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -119,7 +120,8 @@
     "rollup": "^1.16.3",
     "sinon": "^9.0.2",
     "typescript": "4.1.2",
-    "util": "^0.12.1"
+    "util": "^0.12.1",
+    "typedoc": "0.15.0"
   },
   "//smokeTestConfiguration": {
     "skipFolder": true

diff --git a/sdk/core/abort-controller/package.json b/sdk/core/abort-controller/package.json
@@ -30,7 +30,8 @@
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "cross-env TS_NODE_FILES=true TS_NODE_COMPILER_OPTIONS=\"{\\\"module\\\": \\\"commonjs\\\"}\" mocha --require ts-node/register --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --full-trace --no-timeouts test/*.spec.ts",
     "unit-test": "npm run unit-test:node && npm run unit-test:browser",
-    "build:samples": "echo Skipped."
+    "build:samples": "echo Skipped.",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "types": "./types/src/index.d.ts",
   "engine": {
@@ -102,6 +103,7 @@
     "rollup-plugin-sourcemaps": "^0.4.2",
     "rollup-plugin-terser": "^5.1.1",
     "ts-node": "^8.3.0",
-    "typescript": "4.1.2"
+    "typescript": "4.1.2",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-amqp/package.json b/sdk/core/core-amqp/package.json
@@ -56,7 +56,8 @@
     "test": "npm run test:node && npm run test:browser",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "cross-env TS_NODE_FILES=true TS_NODE_COMPILER_OPTIONS=\"{\\\"module\\\":\\\"commonjs\\\"}\" nyc --reporter=lcov --reporter=text-lcov mocha -r ts-node/register -t 50000 --reporter ../../../common/tools/mocha-multi-reporter.js ./test/**/*.spec.ts",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "engines": {
     "node": ">=8.0.0"
@@ -124,6 +125,7 @@
     "sinon": "^9.0.2",
     "ts-node": "^8.3.0",
     "typescript": "4.1.2",
-    "ws": "^7.1.1"
+    "ws": "^7.1.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-asynciterator-polyfill/package.json b/sdk/core/core-asynciterator-polyfill/package.json
@@ -50,7 +50,8 @@
     "unit-test:browser": "echo skipped",
     "unit-test:node": "echo skipped",
     "unit-test": "npm run unit-test:node && npm run unit-test:browser",
-    "build:samples": "echo Skipped."
+    "build:samples": "echo Skipped.",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "sideEffects": true,
   "private": false,
@@ -59,6 +60,7 @@
     "@types/node": "^8.0.0",
     "eslint": "^7.15.0",
     "prettier": "^1.16.4",
-    "typescript": "4.1.2"
+    "typescript": "4.1.2",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-auth/package.json b/sdk/core/core-auth/package.json
@@ -38,7 +38,8 @@
     "test": "npm run build:test && npm run unit-test && npm run integration-test",
     "unit-test:browser": "echo skipped",
     "unit-test:node": "mocha test-dist/**/*.js --reporter ../../../common/tools/mocha-multi-reporter.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -94,6 +95,7 @@
     "rollup-plugin-terser": "^5.1.1",
     "rollup-plugin-visualizer": "^4.0.4",
     "typescript": "4.1.2",
-    "util": "^0.12.1"
+    "util": "^0.12.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-client/package.json b/sdk/core/core-client/package.json
@@ -48,7 +48,8 @@
     "test": "npm run clean && npm run build:ts && npm run bundle:test:node && npm run unit-test:node && npm run bundle:test:browser && npm run unit-test:browser && npm run integration-test:node && npm run integration-test:browser",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "cross-env TS_NODE_FILES=true mocha -r esm -r ts-node/register --timeout 50000 --reporter ../../../common/tools/mocha-multi-reporter.js --colors --exclude \"test/**/*.browser.ts\" \"test/**/*.ts\"",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -121,6 +122,7 @@
     "rollup-plugin-visualizer": "^4.0.4",
     "sinon": "^9.0.2",
     "typescript": "4.1.2",
-    "util": "^0.12.1"
+    "util": "^0.12.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-http/package.json b/sdk/core/core-http/package.json
@@ -101,7 +101,8 @@
     "publish-preview": "mocha --no-colors && shx rm -rf dist/test && node ./.scripts/publish",
     "local": "ts-node ./.scripts/local.ts",
     "latest": "ts-node ./.scripts/latest.ts",
-    "build:samples": "echo Skipped."
+    "build:samples": "echo Skipped.",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "sideEffects": false,
   "nyc": {
@@ -194,6 +195,7 @@
     "ts-node": "^8.3.0",
     "typescript": "4.1.2",
     "uglify-js": "^3.4.9",
-    "xhr-mock": "^2.4.1"
+    "xhr-mock": "^2.4.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-https/package.json b/sdk/core/core-https/package.json
@@ -53,7 +53,8 @@
     "test": "npm run clean && npm run build:ts && npm run bundle:test:node && npm run unit-test:node && npm run bundle:test:browser && npm run unit-test:browser && npm run integration-test:node && npm run integration-test:browser",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "mocha --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js dist-test/index.node.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -137,6 +138,7 @@
     "sinon": "^9.0.2",
     "source-map-support": "^0.5.9",
     "typescript": "4.1.2",
-    "util": "^0.12.1"
+    "util": "^0.12.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-lro/package.json b/sdk/core/core-lro/package.json
@@ -87,7 +87,8 @@
     "unit-test:browser": "npm run build:test && karma start --single-run",
     "unit-test:node": "npm run build:test && nyc mocha --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --timeout 1200000 --full-trace dist-test/index.node.js",
     "pack": "npm pack 2>&1",
-    "prebuild": "npm run clean"
+    "prebuild": "npm run clean",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "sideEffects": false,
   "dependencies": {
@@ -134,6 +135,7 @@
     "rollup-plugin-visualizer": "^4.0.4",
     "ts-node": "^8.3.0",
     "typescript": "4.1.2",
-    "uglify-js": "^3.4.9"
+    "uglify-js": "^3.4.9",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-paging/package.json b/sdk/core/core-paging/package.json
@@ -62,7 +62,8 @@
     "unit-test:browser": "echo skipped",
     "unit-test:node": "echo skipped",
     "unit-test": "npm run unit-test:node && npm run unit-test:browser",
-    "build:samples": "echo Skipped."
+    "build:samples": "echo Skipped.",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "sideEffects": true,
   "private": false,
@@ -75,6 +76,7 @@
     "eslint": "^7.15.0",
     "prettier": "^1.16.4",
     "rimraf": "^3.0.0",
-    "typescript": "4.1.2"
+    "typescript": "4.1.2",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-tracing/package.json b/sdk/core/core-tracing/package.json
@@ -33,7 +33,8 @@
     "test": "npm run build:test && npm run unit-test && npm run integration-test",
     "unit-test:browser": "echo skipped",
     "unit-test:node": "mocha test-dist/**/*.js --reporter ../../../common/tools/mocha-multi-reporter.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -86,6 +87,7 @@
     "rollup-plugin-terser": "^5.1.1",
     "rollup-plugin-visualizer": "^4.0.4",
     "typescript": "4.1.2",
-    "util": "^0.12.1"
+    "util": "^0.12.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/core-xml/package.json b/sdk/core/core-xml/package.json
@@ -47,7 +47,8 @@
     "test": "npm run clean && npm run build:ts && npm run bundle:test:node && npm run unit-test:node && npm run bundle:test:browser && npm run unit-test:browser && npm run integration-test:node && npm run integration-test:browser",
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "mocha --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js dist-test/index.node.js",
-    "unit-test": "npm run unit-test:node && npm run unit-test:browser"
+    "unit-test": "npm run unit-test:node && npm run unit-test:browser",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "files": [
     "dist/",
@@ -117,6 +118,7 @@
     "rollup-plugin-visualizer": "^4.0.4",
     "sinon": "^9.0.2",
     "typescript": "4.1.2",
-    "util": "^0.12.1"
+    "util": "^0.12.1",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/core/logger/package.json b/sdk/core/logger/package.json
@@ -37,7 +37,8 @@
     "unit-test:browser": "karma start --single-run",
     "unit-test:node": "cross-env TS_NODE_FILES=true TS_NODE_COMPILER_OPTIONS=\"{\\\"module\\\": \\\"commonjs\\\"}\" mocha --require ts-node/register --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --full-trace --no-timeouts test/*.spec.ts",
     "unit-test": "npm run unit-test:node && npm run unit-test:browser",
-    "build:samples": "echo Skipped."
+    "build:samples": "echo Skipped.",
+    "docs": "typedoc --excludePrivate --excludeNotExported --mode file --out ./dist/docs ./src"
   },
   "types": "./types/logger.d.ts",
   "engine": {
@@ -111,6 +112,7 @@
     "rollup-plugin-terser": "^5.1.1",
     "sinon": "^9.0.2",
     "ts-node": "^8.3.0",
-    "typescript": "4.1.2"
+    "typescript": "4.1.2",
+    "typedoc": "0.15.0"
   }
 }
diff --git a/sdk/cosmosdb/cosmos/package.json b/sdk/cosmosdb/cosmos/package.json
@@ -131,7 +131,7 @@
     "ts-node": "^8.3.0",
     "tslint": "^5.0.0",
     "tslint-config-prettier": "^1.14.0",
-    "typedoc": "^0.15.0",
+    "typedoc": "0.15.0",
     "typescript": "4.1.2"
   }
 }