[RFC] refactor(docs): move apidocs to /docs

bin/update-template-deps.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Copyright IBM Corp. 2017,2018. All Rights Reserved.
-// Node module: @loopback/cli
+// Node module: loopback-next
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 

docs/README.md

@@ -0,0 +1,17 @@
+# LoopBack 4 documentation
+
+This package contains documentation for LoopBack 4. It's published to npm
+as [@loopback/docs](https://www.npmjs.com/package/@loopback/docs).
+
+## Documentation site
+
+The `site` directory contains pages for http://loopback.io/doc/en/lb4/index.html.
+
+To contribute, please check out https://loopback.io/doc/en/contrib/doc-contrib.html.
+
+## API references
+
+The API references are generated by running `npm run apidocs` at the root
+directory of [loopback-next](https://github.com/strongloop/loopback-next).
+
+[API references](./apidocs.html)

docs/apidocs.html

@@ -13,18 +13,20 @@
       <h2>LoopBack4 packages (local)</h2>
 
       <p>Run the following command to (re)build API doc files:
-      <p><pre><code>$ npx lerna run build:apidocs</code></pre>
+      <p><pre><code>$ npm run apidocs</code></pre>
 
       <h3>List of packages</h3>
       <ul>
-        <li><a href="../packages/authentication/api-docs/index.html">@loopback/authentication</a></li>
-        <li><a href="../packages/context/api-docs/index.html">@loopback/context</a></li>
-        <li><a href="../packages/core/api-docs/index.html">@loopback/core</a></li>
-        <li><a href="../packages/metadata/api-docs/index.html">@loopback/metadata</a></li>
-        <li><a href="../packages/openapi-spec-builder/api-docs/index.html">@loopback/openapi-spec-builder</a></li>
-        <li><a href="../packages/openapi-v3-types/api-docs/index.html">@loopback/openapi-v3-types</a></li>
-        <li><a href="../packages/repository/api-docs/index.html">@loopback/repository</a></li>
-        <li><a href="../packages/rest/api-docs/index.html">@loopback/rest</a></li>
+        <li><a href="./authentication.html">@loopback/authentication</a></li>
+        <li><a href="./context.html">@loopback/context</a></li>
+        <li><a href="./core.html">@loopback/core</a></li>
+        <li><a href="./metadata.html">@loopback/metadata</a></li>
+        <li><a href="./openapi-spec-builder.html">@loopback/openapi-spec-builder</a></li>
+        <li><a href="./openapi-v3-types.html">@loopback/openapi-v3-types</a></li>
+        <li><a href="./openapi-v3.html">@loopback/openapi-v3</a></li>
+        <li><a href="./repository.html">@loopback/repository</a></li>
+        <li><a href="./repository-json-schema.html">@loopback/repository-json-schema</a></li>
+        <li><a href="./rest.html">@loopback/rest</a></li>
       </ul>
     </div>
   </div>

docs/docs.json

@@ -0,0 +1,6 @@
+{
+  "content": ["README.md"],
+  "assets": {
+    "/apidocs.html": "apidocs.html"
+  }
+}

docs/package.json

@@ -16,7 +16,13 @@
     "LoopBack",
     "docs"
   ],
-  "scripts": {},
+  "scripts": {
+    "build:apidocs": "lb-apidocs --html-file=index.html",
+    "clean": "lb-clean loopback-docs*.tgz package api-docs"
+  },
+  "devDependencies": {
+    "@loopback/build": "^0.3.3"
+  },
   "publishConfig": {
     "access": "public"
   },

examples/hello-world/package.json

@@ -12,7 +12,6 @@
     "build": "lb-tsc es2017",
     "build:apidocs": "lb-apidocs",
     "clean": "lb-clean *example-hello-world*.tgz dist package api-docs",
-    "prepublishOnly": "npm run build && npm run build:apidocs",
     "verify": "npm pack && tar xf *example-hello-world*.tgz && tree package && npm run clean",
     "start": "npm run build && node ."
   },

examples/log-extension/package.json

@@ -19,7 +19,6 @@
     "prettier:fix": "npm run prettier:cli -- --write",
     "tslint": "lb-tslint",
     "tslint:fix": "npm run tslint -- --fix",
-    "prepublishOnly": "npm run build",
     "pretest": "npm run clean && npm run build",
     "test": "lb-mocha \"DIST/test/unit/**/*.js\" \"DIST/test/acceptance/**/*.js\"",
     "posttest": "npm run lint",

examples/rpc-server/package.json

@@ -24,8 +24,7 @@
     "pretest": "npm run clean && npm run build",
     "test": "lb-mocha DIST/test",
     "posttest": "npm run lint",
-    "start": "npm run build && node .",
-    "prepublishOnly": "npm run build"
+    "start": "npm run build && node ."
   },
   "repository": {
     "type": "git",

examples/todo/package.json

@@ -12,7 +12,6 @@
     "build": "lb-tsc es2017",
     "build:apidocs": "lb-apidocs",
     "clean": "lb-clean *example-todo*.tgz dist package api-docs",
-    "prepublishOnly": "npm run build && npm run build:apidocs",
     "pretest": "npm run build",
     "test": "lb-mocha \"DIST/test/unit/**/*.js\" \"DIST/test/acceptance/**/*.js\"",
     "unit": "lb-mocha \"DIST/test/unit/**/*.js\"",

package.json

@@ -22,7 +22,8 @@
     "bootstrap": "npm i && lerna bootstrap",
     "release": "npm run build:full && lerna publish",
     "update-template-deps": "node bin/update-template-deps -f",
-    "version": "npm run update-template-deps",
+    "version": "npm run update-template-deps && npm run apidocs",
+    "apidocs": "npm run clean && node bin/run-lerna run build:apidocs --parallel --loglevel=silent",
     "coverage:ci": "node packages/build/bin/run-nyc report --reporter=text-lcov | coveralls",
     "precoverage": "npm test",
     "coverage": "open coverage/index.html",
@@ -39,7 +40,7 @@
     "build:full": "npm run clean:lerna && npm run bootstrap && npm test",
     "pretest": "npm run clean && npm run build",
     "test": "node packages/build/bin/run-nyc npm run mocha --scripts-prepend-node-path",
-    "mocha": "node packages/build/bin/run-mocha \"packages/*/DIST/test/**/*.js\" \"examples/*/DIST/test/**/*.js\" \"packages/cli/test/**/*.js\"",
+    "mocha": "node packages/build/bin/run-mocha \"packages/*/DIST/test/**/*.js\" \"examples/*/DIST/test/**/*.js\" \"packages/cli/test/*.js\" \"packages/build/test/*/*.js\"",
     "posttest": "npm run lint"
   },
   "config": {

packages/authentication/package.json

@@ -11,7 +11,6 @@
     "build:apidocs": "lb-apidocs",
     "clean": "lb-clean loopback-authentication*.tgz dist package api-docs",
     "integration": "lb-mocha \"DIST/test/integration/**/*.js\"",
-    "prepublishOnly": "npm run build && npm run build:apidocs",
     "pretest": "npm run build",
     "test": "lb-mocha \"DIST/test/unit/**/*.js\" \"DIST/test/integration/**/*.js\" \"DIST/test/acceptance/**/*.js\"",
     "unit": "lb-mocha \"DIST/test/unit/**/*.js\"",
@@ -46,7 +45,6 @@
     "index.js",
     "index.d.ts",
     "dist/src",
-    "api-docs",
     "src"
   ],
   "repository": {

packages/boot/package.json

@@ -15,7 +15,6 @@
     "build:dist": "lb-tsc es2017",
     "build:apidocs": "lb-apidocs",
     "clean": "lb-clean loopback-boot*.tgz dist package api-docs",
-    "prepublishOnly": "npm run build && npm run build:apidocs",
     "pretest": "npm run build:current",
     "integration": "lb-mocha \"DIST/test/integration/**/*.js\"",
     "test": "lb-mocha \"DIST/test/unit/**/*.js\" \"DIST/test/integration/**/*.js\" \"DIST/test/acceptance/**/*.js\"",
@@ -50,7 +49,6 @@
     "dist/index.js",
     "dist/index.js.map",
     "dist/index.d.ts",
-    "api-docs",
     "src"
   ],
   "repository": {

packages/build/bin/compile-package.js

@@ -72,10 +72,11 @@ function run(argv, options) {
       // No local tsconfig.build.json or tsconfig.json found
       var baseConfigFile = path.join(rootDir, 'config/tsconfig.common.json');
       baseConfigFile = path.relative(packageDir, baseConfigFile);
-      if (baseConfigFile.indexOf('../') !== 0) {
+      if (baseConfigFile.indexOf('..' + path.sep) !== 0) {
         // tsconfig only supports relative or rooted path
-        baseConfigFile = './' + baseConfigFile;
+        baseConfigFile = '.' + path.sep + baseConfigFile;
       }
+      baseConfigFile = baseConfigFile.replace(/\\/g, '/');
       // Create tsconfig.json under the package as it's required to parse
       // include/exclude correctly
       tsConfigFile = path.join(packageDir, 'tsconfig.json');

packages/build/bin/generate-apidocs.js

@@ -42,7 +42,32 @@ function run(argv, options) {
     args.push('--tsconfig', config);
   }
   if (!utils.isOptionSet(apidocsOpts, '--out', '-o')) {
-    args.push('-o', 'api-docs');
+    let out = 'api-docs';
+    if (process.env.LERNA_ROOT_PATH) {
+      out = path.join(process.env.LERNA_ROOT_PATH, `docs/${out}`);
+    }
+    args.push('-o', out);
+  }
+  if (process.env.LERNA_ROOT_PATH) {
+    const pkg = require(path.join(utils.getPackageDir(), 'package.json'));
+    // Skip private packages for repo level apidocs
+    if (pkg.private) return;
+    if (!utils.isOptionSet(apidocsOpts, '--html-file')) {
+      // Generate api docs into loopback-next/docs/api-docs/<pkg-name>
+      let name = pkg.name;
+
+      const index = pkg.name.lastIndexOf('/');
+      if (index !== -1) {
+        name = pkg.name.substring(index + 1);
+      }
+      args.push('--html-file', `${name}.html`);
+    }
+
+    if (!utils.isOptionSet(apidocsOpts, '--skip-public-assets')) {
+      if (pkg.name !== '@loopback/docs') {
+        args.push('--skip-public-assets');
+      }
+    }
   }
   args.push(...apidocsOpts);
   return utils.runCLI('strong-docs/bin/cli', args, options);

packages/build/bin/utils.js

@@ -181,7 +181,10 @@ function runShell(command, args, options) {
  * @param {string[]} optionNames
  */
 function isOptionSet(opts, ...optionNames) {
-  return opts.some(o => optionNames.indexOf(o) !== -1);
+  return opts.some(opt =>
+    // It can be --my-opt or --my-opt=my-value
+    optionNames.some(name => name === opt || opt.startsWith(`${name}=`))
+  );
 }
 
 exports.getCompilationTarget = getCompilationTarget;

packages/build/test/fixtures/package.json → packages/build/test/integration/fixtures/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "ts-test-proj",
+  "name": "@loopback/ts-test-proj",
   "version": "1.0.0",
   "description": "Test",
   "scripts": {

packages/build/test/integration/scripts.integration.js

@@ -12,7 +12,7 @@ const fs = require('fs-extra');
 describe('build', function() {
   this.timeout(30000);
   var cwd = process.cwd();
-  var projectDir = path.resolve(__dirname, '../fixtures');
+  var projectDir = path.resolve(__dirname, './fixtures');
 
   function cleanup() {
     var run = require('../../bin/run-clean');
@@ -50,41 +50,40 @@ describe('build', function() {
         'tsconfig.json should have been created'
       );
       var tsConfig = fs.readJSONSync(path.join(projectDir, 'tsconfig.json'));
-      assert.equal(tsConfig.extends, '../../config/tsconfig.common.json');
+      assert.equal(tsConfig.extends, '../../../config/tsconfig.common.json');
       done();
     });
   });
 
   it('honors tsconfig.build.json over tsconfig.json', () => {
     fs.writeJSONSync('tsconfig.build.json', {
-      extends: '../../config/tsconfig.common.json',
+      extends: '../../../config/tsconfig.common.json',
       include: ['src', 'test'],
       exclude: ['node_modules/**', 'packages/*/node_modules/**', '**/*.d.ts'],
     });
     fs.writeJSONSync('tsconfig.json', {
-      extends: '../../config/tsconfig.common.json',
+      extends: '../../../config/tsconfig.common.json',
       include: ['src', 'test'],
       exclude: ['node_modules/**', 'packages/*/node_modules/**', '**/*.d.ts'],
     });
     var run = require('../../bin/compile-package');
     var command = run(['node', 'bin/compile-package'], true);
     assert(
-      command.indexOf('-p ' + path.join(projectDir, 'tsconfig.build.json')) !==
-        -1,
+      command.indexOf('-p tsconfig.build.json') !== -1,
       'project level tsconfig.build.json should be honored'
     );
   });
 
   it('honors tsconfig.json if tsconfig.build.json is not present', () => {
     fs.writeJSONSync('tsconfig.json', {
-      extends: '../../config/tsconfig.common.json',
+      extends: '../../../config/tsconfig.common.json',
       include: ['src', 'test'],
       exclude: ['node_modules/**', 'packages/*/node_modules/**', '**/*.d.ts'],
     });
     var run = require('../../bin/compile-package');
     var command = run(['node', 'bin/compile-package'], true);
     assert(
-      command.indexOf('-p ' + path.join(projectDir, 'tsconfig.json')) !== -1,
+      command.indexOf('-p tsconfig.json') !== -1,
       'project level tsconfig.json should be honored'
     );
   });
@@ -212,6 +211,30 @@ describe('build', function() {
     );
   });
 
+  it('honors --skip-public-assets for apidocs', () => {
+    var run = require('../../bin/generate-apidocs');
+    var command = run(
+      ['node', 'bin/generate-apidocs', '--skip-public-assets'],
+      true
+    );
+    assert(
+      command.indexOf('--skip-public-assets') !== -1,
+      '--skip-public-assets should be honored'
+    );
+  });
+
+  it('honors --html-file for apidocs', () => {
+    var run = require('../../bin/generate-apidocs');
+    var command = run(
+      ['node', 'bin/generate-apidocs', '--html-file=my.html'],
+      true
+    );
+    assert(
+      command.indexOf('--html-file=my.html') !== -1,
+      '--html-file should be honored'
+    );
+  });
+
   it('runs tslint against ts files', done => {
     var run = require('../../bin/run-tslint');
     var childProcess = run(['node', 'bin/run-tslint']);
@@ -294,4 +317,42 @@ describe('build', function() {
     );
     assert(command.indexOf('rm -rf ./dist') !== -1);
   });
+
+  describe('with LERNA_ROOT_PATH', () => {
+    const repoRoot = path.join(__dirname, '../../../..');
+    before(() => (process.env.LERNA_ROOT_PATH = repoRoot));
+
+    it('sets --skip-public-assets for apidocs', () => {
+      var run = require('../../bin/generate-apidocs');
+      var command = run(['node', 'bin/generate-apidocs'], true);
+      assert(
+        command.indexOf('--skip-public-assets') !== -1,
+        '--skip-public-assets should be set by default'
+      );
+    });
+
+    it('sets --html-file for apidocs', () => {
+      var run = require('../../bin/generate-apidocs');
+      var command = run(['node', 'bin/generate-apidocs'], true);
+      assert(
+        command.indexOf('--html-file ts-test-proj.html') !== -1,
+        '--html-file should be set to the package name by default'
+      );
+    });
+
+    it('sets --project option for tsc', () => {
+      var run = require('../../bin/compile-package');
+      var command = run(['node', 'bin/compile-package'], true);
+      const tsConfig = path.relative(
+        repoRoot,
+        path.join(__dirname, './fixtures/tsconfig.json')
+      );
+      assert(
+        command.indexOf(`-p ${tsConfig}`) !== -1,
+        '-p should be set relative to the monorepo root'
+      );
+    });
+
+    after(() => delete process.env.LERNA_ROOT_PATH);
+  });
 });

packages/context/package.json

@@ -10,7 +10,6 @@
     "build": "lb-tsc es2017",
     "build:apidocs": "lb-apidocs",
     "clean": "lb-clean loopback-context*.tgz dist package api-docs",
-    "prepublishOnly": "npm run build && npm run build:apidocs",
     "pretest": "npm run build",
     "test": "lb-mocha \"DIST/test/unit/**/*.js\" \"DIST/test/acceptance/**/*.js\"",
     "unit": "lb-mocha \"DIST/test/unit/**/*.js\"",
@@ -47,7 +46,6 @@
     "index.js",
     "index.d.ts",
     "dist/src",
-    "api-docs",
     "src"
   ],
   "repository": {

packages/core/package.json

@@ -10,7 +10,6 @@
     "build": "lb-tsc es2017",
     "build:apidocs": "lb-apidocs",
     "clean": "lb-clean loopback-core*.tgz dist package api-docs",
-    "prepublishOnly": "npm run build && npm run build:apidocs",
     "pretest": "npm run build",
     "integration": "lb-mocha \"DIST/test/integration/**/*.js\"",
     "test": "lb-mocha \"DIST/test/unit/**/*.js\" \"DIST/test/integration/**/*.js\" \"DIST/test/acceptance/**/*.js\"",
@@ -36,7 +35,6 @@
     "dist/src",
     "dist/index.d.ts",
     "dist/index.js.map",
-    "api-docs",
     "src"
   ],
   "repository": {