docs: use typedoc to generate a json file documentation dump of all components (#1887)

Author: Eric Jimenez

GENERATING_API_DOCS.md

@@ -0,0 +1,30 @@
+# Generating API Docs with Typedoc
+[Typedoc](http://typedoc.org/) is a documentation generator for TypeScript projects.
+
+Refer to `typedoc.json` for build configuration.
+
+1. `npm install`
+2. `npm run api`
+
+TypeDoc will leverage the typings file to generate docs. The output will be located in `/dist/api/api.json`.
+
+## FAQ
+
+### How do I stop HTML generation and focus only on JSON?
+Currently not possible, submitted a feature request: https://github.com/TypeStrong/typedoc/issues/337
+
+### How do I prevent `Cannot find name` errors?
+When typedoc is invoked tsconfig and typings file must be in the path.
+
+### How do we omit constructors or other methods from the components?
+You can either ignore them from the output file, or use the `@hidden` tag in the source code to omit a method or
+property from being generated as docs. The recommended approach is to ignore them since adding the hidden tag will
+create a lot of noise
+
+### Can we detect Inputs and Outputs from Angular components?
+Yes, check the decorators key-value on the json file for that particular component.
+
+### Can we generate a json file for a specific component?
+Yes, if we were to invoke `./node_modules/.bin/typedoc --options ./src/lib/typedoc.json --ignoreCompilerErrors ./src/lib/button`
+We could theoretically generate a json file just for button, but we would ignore compiler errors because button does
+not have a tsconfig or typings file local to its implementation.

package.json

@@ -15,7 +15,9 @@
     "stylelint": "gulp lint",
     "e2e": "gulp e2e",
     "deploy": "firebase deploy",
-    "webdriver-manager": "webdriver-manager"
+    "webdriver-manager": "webdriver-manager",
+    "docs": "gulp docs",
+    "api": "gulp api"
   },
   "version": "2.0.0-alpha.10",
   "license": "MIT",
@@ -88,6 +90,7 @@
     "symlink-or-copy": "^1.0.1",
     "ts-node": "^0.7.3",
     "tslint": "^3.13.0",
+    "typedoc": "^0.5.1",
     "typescript": "^2.0.2",
     "typings": "^1.3.1",
     "which": "^1.2.4"

src/lib/button/button.ts

@@ -140,8 +140,8 @@ export class MdAnchor extends MdButton {
     return this.disabled ? -1 : 0;
   }
 
-  @HostBinding('attr.aria-disabled')
   /** Gets the aria-disabled value for the component, which must be a string for Dart. */
+  @HostBinding('attr.aria-disabled')
   get isAriaDisabled(): string {
     return this.disabled ? 'true' : 'false';
   }

src/lib/typedoc.json

@@ -0,0 +1,20 @@
+{
+  "mode": "modules",
+  "out": "./dist/api",
+  "json": "./dist/api/api.json",
+  "theme": "default",
+  "experimentalDecorators": "true",
+  "emitDecoratorMetadata": "true",
+  "excludePrivate": "true",
+  "excludeExternals": "true",
+  "includeDeclarations": "true",
+  "target": "ES6",
+  "exclude": "**/+(*.spec.ts|*.scss|*.html)",
+  "name": "Angular Material",
+  "moduleResolution": "node",
+  "preserveConstEnums": "true",
+  "stripInternal": "true",
+  "suppressExcessPropertyErrors": "true",
+  "suppressImplicitAnyIndexErrors": "true",
+  "module": "commonjs"
+}

tools/gulp/gulpfile.ts

@@ -9,3 +9,4 @@ import './tasks/lint';
 import './tasks/release';
 import './tasks/serve';
 import './tasks/unit-test';
+import './tasks/docs';

tools/gulp/tasks/docs.ts

@@ -1,15 +1,22 @@
 import gulp = require('gulp');
 const markdown = require('gulp-markdown');
 const transform = require('gulp-transform');
+import {task} from 'gulp';
+import * as path from 'path';
 
+import {SOURCE_ROOT, PROJECT_ROOT} from '../constants';
+import {
+    execNodeTask
+} from '../task_helpers';
+
+const typedocPath = path.relative(PROJECT_ROOT, path.join(SOURCE_ROOT, 'lib/typedoc.json'));
 
 // Our docs contain comments of the form `<!-- example(...) -->` which serve as placeholders where
 // example code should be inserted. We replace these comments with divs that have a
 // `material-docs-example` attribute which can be used to locate the divs and initialize the example
 // viewer.
 const EXAMPLE_PATTERN = /<!--\W*example\(([^)]+)\)\W*-->/g;
 
-
 gulp.task('docs', () => {
   return gulp.src(['src/lib/**/*.md'])
       .pipe(markdown())
@@ -18,3 +25,5 @@ gulp.task('docs', () => {
               `<div material-docs-example="${name}"></div>`)))
       .pipe(gulp.dest('dist/docs'));
 });
+
+task('api', execNodeTask('typedoc', ['--options', typedocPath, './src/lib']));