feat(tsdocs): add integration with api-extractor/documenter

.gitignore

@@ -12,7 +12,14 @@ benchmark/dist
 **/package
 .sandbox
 packages/cli/generators/datasource/connectors.json
-docs/site/readmes
+packages/tsdocs/fixtures/monorepo/docs
+/docs/site/readmes
+/docs/apidocs/reports-temp
+/docs/apidocs/models
+
+# TBD: Exclude api reports from git for now
+/docs/apidocs/reports
+/docs/site/apidocs
 
 # Exclude all files under sandbox except README.md and example
 /sandbox/*

.prettierignore

@@ -1,6 +1,10 @@
 /coverage
 **/*/api-docs
+/docs/apidocs
+/docs/site/apidocs
 packages/cli/generators/*/templates
+packages/tsdocs/fixtures/monorepo/docs
+packages/tsdocs/fixtures/monorepo/**/dist
 **/.sandbox
 packages/*/dist
 examples/*/dist

CODEOWNERS

@@ -25,6 +25,7 @@ packages/repository-json-schema/* @bajtos
 packages/rest/* @bajtos @raymondfeng
 packages/service-proxy/* @raymondfeng
 packages/testlab/* @bajtos
+packages/tsdocs/* @raymondfeng
 examples/todo/* @bajtos @hacksparrow
 examples/express-composition/* @nabdelgadir
 examples/greeter-extension/* @raymondfeng

bin/build-docs-site.sh

@@ -21,8 +21,9 @@ DIR=`dirname $0`
 REPO_ROOT=$DIR/..
 pushd $REPO_ROOT >/dev/null
 
-# Update README duplicates inside docs/site/readmes
-node docs/bin/copy-readmes.js
+# Update apidocs
+lerna bootstrap --scope @loopback/tsdocs
+lerna run --scope @loopback/docs prepack
 
 # Clean up sandbox/loopback.io directory
 rm -rf sandbox/loopback.io/

docs/package.json

@@ -16,8 +16,8 @@
   ],
   "scripts": {
     "build:apidocs": "lb-apidocs --html-file=index.html",
-    "prepublishOnly": "node ./bin/copy-readmes",
-    "clean": "lb-clean loopback-docs*.tgz package api-docs site/readmes"
+    "prepack": "node ./bin/copy-readmes && cd .. && npm run tsdocs",
+    "clean": "lb-clean loopback-docs*.tgz package api-docs apidocs site/readmes site/apidocs"
   },
   "devDependencies": {
     "@loopback/build": "^1.5.5"

docs/site/MONOREPO.md

@@ -36,6 +36,7 @@ The [loopback-next](https://github.com/strongloop/loopback-next) repository uses
 | [rest](https://github.com/strongloop/loopback-next/tree/master/packages/rest)                                       | @loopback/rest                        | Expose controllers as REST endpoints and route REST API requests to controller methods                                                                                                                                                                                                           |
 | [service-proxy](https://github.com/strongloop/loopback-next/tree/master/packages/service-proxy)                     | @loopback/service-proxy               | A common set of interfaces for interacting with service oriented backends such as REST APIs, SOAP Web Services, and gRPC microservices                                                                                                                                                           |
 | [testlab](https://github.com/strongloop/loopback-next/tree/master/packages/testlab)                                 | @loopback/testlab                     | A collection of test utilities we use to write LoopBack tests                                                                                                                                                                                                                                    |
+| [tsdocs](https://github.com/strongloop/loopback-next/tree/master/packages/tsdocs)                                   | @loopback/tsdocs                      | An internal package to generate api docs using Microsoft api-extractor and api-documenter                                                                                                                                                                                                        |
 | [tslint-config](https://github.com/strongloop/loopback-next/tree/master/packages/tslint-config)                     | @loopback/tslint-config               | Shared TSLint config to enforce a consistent code style for LoopBack development                                                                                                                                                                                                                 |
 
 We use npm scripts declared in

docs/site/sidebars/lb4_sidebar.yml

@@ -393,6 +393,10 @@ children:
   url: FAQ.html
   output: 'web, pdf'
 
+- title: 'API docs'
+  url: apidocs.index.html
+  output: 'web, pdf'
+
 - title: 'Reference'
   url: Reference.html
   output: 'web, pdf'

greenkeeper.json

@@ -34,6 +34,7 @@
         "packages/rest/package.json",
         "packages/service-proxy/package.json",
         "packages/testlab/package.json",
+        "packages/tsdocs/package.json",
         "packages/tslint-config/package.json"
       ]
     }

package.json

@@ -41,6 +41,7 @@
     "version": "npm run update-packages && git add greenkeeper.json \"**/package-lock.json\" && npm run update-template-deps && npm run apidocs",
     "outdated": "npm outdated --depth 0 && lerna exec --no-bail \"npm outdated --depth 0\"",
     "apidocs": "node bin/run-lerna run build:apidocs",
+    "tsdocs": "lerna run --scope @loopback/tsdocs build:tsdocs",
     "coverage:ci": "node packages/build/bin/run-nyc report --reporter=text-lcov | coveralls",
     "precoverage": "npm test",
     "coverage": "open coverage/index.html",

packages/build/index.js

@@ -16,3 +16,9 @@ exports.clean = require('./bin/run-clean');
 const utils = require('./bin/utils');
 exports.runCLI = utils.runCLI;
 exports.runShell = utils.runShell;
+
+const path = require('path');
+exports.typeScriptPath = path.resolve(
+  require.resolve('typescript/package.json'),
+  '..',
+);

packages/tsdocs/.npmrc

@@ -0,0 +1 @@
+package-lock=true

packages/tsdocs/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2019. All Rights Reserved.
+Node module: @loopback/tsdocs
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT license
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/tsdocs/README.md

@@ -0,0 +1,73 @@
+# @loopback/tsdocs
+
+This module provides [API docs](https://github.com/Microsoft/tsdoc) generation
+for `@loopback/*` packages.
+
+It's built on top of https://api-extractor.com/:
+
+- https://github.com/Microsoft/web-build-tools/tree/master/apps/api-extractor
+- https://github.com/Microsoft/web-build-tools/tree/master/apps/api-documenter
+
+## Basic Use
+
+### Build api reports and doc models
+
+```sh
+npm run extract-apidocs -- --report
+```
+
+The command above will traverse all TypeScript packages in the monorepo and run
+`api-extractor` to generate api reports and doc models into
+`loopback-next/docs/apidocs`:
+
+- `reports`: api reports
+- `reports-temp`: temporary api reports
+- `models`: doc models
+
+### Generate api docs as markdown files
+
+```sh
+npm run document-apidocs
+```
+
+It runs `api-documenter` to generate markdown files into
+`loopback-next/docs/site/apidocs`.
+
+### Update api docs for Jekyll site
+
+```sh
+npm run update-apidocs
+```
+
+It adds Jekyll metadata to markdown files in `loopback-next/docs/site/apidocs`
+and generates `loopback-next/docs/site/apidocs/index.md` as the index page.
+
+To run all steps together:
+
+```sh
+npm run build:apidocs
+```
+
+## Installation
+
+```sh
+npm install --save @loopback/tsdocs
+```
+
+## Contributions
+
+- [Guidelines](https://github.com/strongloop/loopback-next/blob/master/docs/CONTRIBUTING.md)
+- [Join the team](https://github.com/strongloop/loopback-next/issues/110)
+
+## Tests
+
+Run `npm test` from the root folder.
+
+## Contributors
+
+See
+[all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
+
+## License
+
+MIT

packages/tsdocs/bin/extract-apis.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/tsdocs
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/**
+ * Run api-extractor against the monorepo
+ */
+const runExtractorForMonorepo = require('..').runExtractorForMonorepo;
+
+const silent = process.argv.includes('--silent');
+const dryRun = process.argv.includes('--dry-run');
+
+/**
+ * The option to control if reports are generated by api-extractor
+ */
+const apiReportEnabled = process.argv.includes('--report');
+
+async function main() {
+  await runExtractorForMonorepo({silent, dryRun, apiReportEnabled});
+}
+
+main();

packages/tsdocs/bin/update-apidocs.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/tsdocs
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/**
+ * Update generated api md files with Jekyll macros and create index page
+ */
+const updateApiDocs = require('..').updateApiDocs;
+const silent = process.argv.includes('--silent');
+const dryRun = process.argv.includes('--dry-run');
+
+async function main() {
+  await updateApiDocs({silent, dryRun});
+}
+
+main();

packages/tsdocs/fixtures/README.md

@@ -0,0 +1,13 @@
+# fixtures/monorepo
+
+This `monorepo` directory contains a simplified monorepo managed by lerna. It's
+used to mimic `loopback-next` to test `@loopback/tsdocs`.
+
+# Rebuild
+
+If you have to change the source code for the fixture, run the following command
+to rebuild.
+
+```sh
+npm run build
+```

packages/tsdocs/fixtures/monorepo/lerna.json

@@ -0,0 +1,17 @@
+{
+  "lerna": "3.3.0",
+  "packages": [
+    "packages/*",
+    "docs"
+  ],
+  "version": "independent",
+  "command": {
+    "run": {
+      "prefix": false,
+      "loglevel": "silent",
+      "stream": true,
+      "concurrency": 8,
+      "sort": true
+    }
+  }
+}

packages/tsdocs/fixtures/monorepo/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "root",
+  "version": "1.0.0",
+  "description": "Root",
+  "scripts": {
+    "clean": "../../../../node_modules/.bin/lerna run clean",
+    "bootstrap": "../../../../node_modules/.bin/lerna bootstrap",
+    "build": "npm -s run bootstrap && npm -s run clean && ../../../../node_modules/.bin/lerna run build"
+  },
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@loopback/build": "file:../../../build"
+  }
+}

packages/tsdocs/fixtures/monorepo/packages/pkg1/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Base class for pets
+ */
+export declare class Pet {
+    readonly name: string;
+    readonly kind: string;
+    /**
+     * Create a pet
+     * @param name - Name of the pet
+     * @param kind - Kind of the pet
+     */
+    constructor(name: string, kind: string);
+    /**
+     * Greet the pet
+     * @param msg - Message for the greeting
+     * @returns The description
+     */
+    greet(msg: string): string;
+}

packages/tsdocs/fixtures/monorepo/packages/pkg1/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "pkg1",
+  "version": "1.0.0",
+  "description": "Test package 1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "scripts": {
+    "build": "lb-tsc es2017 --outDir dist",
+    "clean": "lb-clean dist"
+  }
+}

packages/tsdocs/fixtures/monorepo/packages/pkg1/src/index.ts

@@ -0,0 +1,24 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/**
+ * Base class for pets
+ */
+export class Pet {
+  /**
+   * Create a pet
+   * @param name - Name of the pet
+   * @param kind - Kind of the pet
+   */
+  constructor(public readonly name: string, public readonly kind: string) {}
+
+  /**
+   * Greet the pet
+   * @param msg - Message for the greeting
+   * @returns The description
+   */
+  greet(msg: string) {
+    return `[${msg}] ${this.name}:${this.kind}`;
+  }
+}

packages/tsdocs/fixtures/monorepo/packages/pkg1/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": "@loopback/build/config/tsconfig.common.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}