chore(docs): Improve scripts/docs.js script: Expect ui-router-core to be installed as a peer to angular-ui-router. This enables docs building off master/master and preserves GitHub source lookup.

Author: christopherthielen

package.json

@@ -3,7 +3,7 @@
   "description": "State-based routing for AngularJS 1.x",
   "version": "1.0.0-beta.4",
   "scripts": {
-    "clean": "shx rm -rf lib lib-esm _doc release",
+    "clean": "shx rm -rf lib lib-esm _doc build release *.log",
     "build": "tsc && tsc -m es6 --outDir lib-esm && npm run fixdts",
     "fixdts": "dts-downlevel 'lib/**/*.d.ts' 'lib-esm/**/*.d.ts'",
     "package": "npm run clean && npm run build && webpack --hide-modules",
@@ -15,7 +15,7 @@
     "test:integrate": "tsc && npm run test:ng12 && npm run test:ng13 && npm run test:ng14 && npm run test:ng15",
     "watch": "karma start --singleRun=false --autoWatch=true --autoWatchInterval=1",
     "debug": "karma start --singleRun=false --autoWatch=true --autoWatchInterval=1 --browsers=Chrome",
-    "docs": "typedoc --tsconfig tsconfig.typedoc.json --readme README.md --name 'angular-ui-router' --theme node_modules/ui-router-typedoc-themes/bin/default --out _doc --internal-aliases internal,coreapi,ng1api --external-aliases internalapi,external --navigation-label-globals angular-ui-router"
+    "docs": "./scripts/docs.js"
   },
   "homepage": "https://ui-router.github.io",
   "contributors": [
@@ -98,7 +98,7 @@
     "typedoc-plugin-internal-external": "^1.0.0",
     "typedoc-plugin-ui-router": "^1.0.0",
     "typescript": "^2.1.4",
-    "ui-router-typedoc-themes": "^1.0.0",
+    "ui-router-typedoc-themes": "^1.0.1",
     "watch": "^0.18.0",
     "webpack": "1.x",
     "webpack-dev-server": "1.x",

scripts/docs.js

@@ -16,45 +16,41 @@ let typedocCmd = [
 ].join(" ");
 
 let PROJECTDIR = path.join(__dirname, '..');
-// let DOCGENDIR = '_docsgen';
 let PROJ2 = 'ui-router-core';
 
 shelljs.pushd(PROJECTDIR);
 
-// shelljs.rm('-rf', DOCGENDIR);
-// shelljs.mkdir(DOCGENDIR);
-
-// shelljs.cp('-R', 'src', DOCGENDIR);
-// shelljs.mkdir(path.join(DOCGENDIR, PROJ2));
-// shelljs.cp('-R', path.join('..', PROJ2, '.git'), path.join(DOCGENDIR, PROJ2, '.git'));
-// shelljs.cp('-R', path.join('..', PROJ2, 'src'), path.join(DOCGENDIR, PROJ2, 'src'));
-
-// shelljs.ln('-s', path.join('..', '..', PROJ2), path.join(DOCGENDIR, PROJ2));
-
+// Make a backup of the source directory
 shelljs.mv('src', 'src.bak');
 shelljs.cp('-r', 'src.bak', 'src');
 
 let arr = [];
+// This replaces "ui-router-core" with "../../../ui-router-core"
+// while accounting for how many "../../" should be prepended
 for (var i = 0; i < 5; i++) {
   arr.push(arr.length);
 
   let dots = arr.map((val) => '..').join('/');
   let stars = arr.map((val) => '*').join('/');
 
+  // Replace references to "ui-router-core/lib" with "../ui-router-core/lib" for typedoc
   replaceInFiles.sync({
     replace: / (['"])ui-router-core\/lib/,
-    with: ' $1' + dots + '/ui-router-core/src',
+    with: ' $1' + dots + '/../ui-router-core/src',
     files: 'src/' + stars + '.ts'
   });
 
+  // Replace references to "ui-router-core" with "../ui-router-core" for typedoc
   replaceInFiles.sync({
     replace: / (['"])ui-router-core/,
-    with: ' $1' + dots + '/ui-router-core/src',
+    with: ' $1' + dots + '/../ui-router-core/src',
     files: 'src/' + stars + '.ts'
   });
 }
 
+// Run typedoc
 shelljs.exec(typedocCmd);
 
+// Restore original sources
 shelljs.rm('-rf', 'src');
 shelljs.mv('src.bak', 'src');

src/directives/stateDirectives.ts

@@ -3,7 +3,9 @@
  *
  * These directives are used in templates to create viewports and navigate to states
  *
- * @ng1api @preferred @module directives
+ * @ng1api
+ * @preferred
+ * @module directives
  */ /** for typedoc */
 import { ng as angular } from "../angular";
 import { IAugmentedJQuery, ITimeoutService, IScope, IInterpolateService } from "angular";

src/directives/viewDirective.ts

@@ -1,4 +1,7 @@
-/** @ng1api @module directives */ /** for typedoc */
+/** 
+ * @ng1api 
+ * @module directives 
+ */ /** for typedoc */
 import { ng as angular } from "../angular";
 import {
     IInterpolateService, IScope, ITranscludeFunction, IAugmentedJQuery,

src/injectables.ts

@@ -42,7 +42,9 @@
  * - [[$stateParams]]: State param values for pending Transition (deprecated)
  * - Any resolve data defined using [[Ng1StateDeclaration.resolve]]
  *
- * @ng1api @preferred @module injectables
+ * @ng1api
+ * @preferred
+ * @module injectables
  */ /** */
 
 import { StateProvider } from "./stateProvider";

src/interface.ts

@@ -1,4 +1,7 @@
-/** @ng1api @module ng1 */ /** */
+/**
+ * @ng1api
+ * @module ng1
+ */ /** */
 import { StateDeclaration, _ViewDeclaration, IInjectable, Transition, HookResult } from "ui-router-core";
 
 

tsconfig.typedoc.json

@@ -11,6 +11,7 @@
   },
   "files": [
     "src/index.ts",
+    "../ui-router-core/src/index.ts",
     "node_modules/typedoc/node_modules/typescript/lib/lib.es6.d.ts"
   ]
 }