Add typedoc to build docs from ESDoc comments (#135)

* Add typedoc to build docs

* Cleanup comments

package.json

@@ -9,7 +9,7 @@
     "packages/*"
   ],
   "scripts": {
-    "build": "polkadot-dev-build-ts && (cd packages/dev && copyfiles config/* scripts/* skeleton/* build) && (cd packages/dev-react && copyfiles config/* scripts/* skeleton/* build)",
+    "build": "polkadot-dev-build-ts && (cd packages/dev && copyfiles config/* scripts/* skeleton/* build) && (cd packages/dev-react && copyfiles config/* scripts/* skeleton/* build) && polkadot-dev-build-docs",
     "check": "tslint --project . && tsc --noEmit",
     "clean": "polkadot-dev-clean-build",
     "postinstall": "./packages/dev/scripts/polkadot-dev-yarn-only.js",

packages/dev-react/src/index.tsx

@@ -4,20 +4,17 @@
 
 import * as React from 'react';
 
-// cross-package imports
-// import { echo } from '@polkadot/dev';
-
-type Props = {
+export type Props = {
   className: string,
   value: string
 };
 
-type State = {
+export type State = {
   value: string
 };
 
 /**
- * @summary This is just a test file to test the doc generation
+ * This is just a test file to test the doc generation
  */
 export default class App extends React.PureComponent<Props, State> {
   state: State;

packages/dev/package.json

@@ -4,7 +4,7 @@
   "description": "A collection of shared CI scripts and development environment used by @polkadot projects",
   "bin": {
     "polkadot-dev-build-babel": "./scripts/polkadot-dev-build-babel.sh",
-    "polkadot-dev-build-docs": "./scripts/polkadot-dev-build-docs.js",
+    "polkadot-dev-build-docs": "./scripts/polkadot-dev-build-docs.sh",
     "polkadot-dev-build-travis": "./scripts/polkadot-dev-build-travis.sh",
     "polkadot-dev-build-ts": "./scripts/polkadot-dev-build-ts.sh",
     "polkadot-dev-clean-branches": "./scripts/polkadot-dev-clean-branches.sh",
@@ -86,6 +86,7 @@
     "rimraf": "^2.6.2",
     "tslint": "^5.10.0",
     "tslint-config-semistandard": "^7.0.0",
+    "typedoc": "^0.11.1",
     "typescript": "^2.9.2"
   }
 }

packages/dev/scripts/polkadot-dev-build-docs.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Copyright 2017-2018 @polkadot/dev authors & contributors
+# This software may be modified and distributed under the terms
+# of the ISC license. See the LICENSE file for details.
+
+set -e
+
+function build_docs () {
+  ROOT=$1
+
+  if [ ! -f "$ROOT/.nodoc" ]; then
+    echo ""
+    echo "*** Building via typedoc"
+
+    DOCROOT=${ROOT/packages/.}
+    typedoc --out ./docs/$DOCROOT $ROOT/src
+
+    echo ""
+    echo "*** Docs completed"
+  fi
+}
+
+PACKAGES=( $(ls -1d packages/*) )
+
+for PACKAGE in "${PACKAGES[@]}"; do
+  echo ""
+  echo "*** Executing in $PACKAGE"
+
+  build_docs "$PACKAGE"
+done
+
+cd ..
+
+exit 0

packages/dev/src/index.ts

@@ -3,6 +3,6 @@
 // of the ISC license. See the LICENSE file for details.
 
 /**
- * @summary This is just a test file to test the doc generation
+ * This is just a test file to test the doc generation
  */
 export const echo = (value: string) => value;

packages/dev/src/test1/bar.ts

@@ -1,15 +1,3 @@
 // Copyright 2017-2018 @polkadot/dev authors & contributors
 // This software may be modified and distributed under the terms
 // of the ISC license. See the LICENSE file for details.
-
-/**
- * @name bar
- * @signature bar (never: number, something: string): boolean
- * @summary This is the summary for bar
- * @description
- * This is the description with another line
- * @example
- * const bar = require('./bar');
- *
- * bar();
- */

packages/dev/src/test1/foo.ts

@@ -1,20 +1,3 @@
 // Copyright 2017-2018 @polkadot/dev authors & contributors
 // This software may be modified and distributed under the terms
 // of the ISC license. See the LICENSE file for details.
-
-/**
- * @name foo
- * @signature foo (something: string): boolean
- * @summary This is the summary
- * @description
- * This is the description
- * With another line
- * @example
- * const foo = require('./foo');
- *
- * try {
- *   foo();
- * } catch (error) {
- *   console.error
- * }
- */

packages/dev/src/test1/index.ts

@@ -3,6 +3,7 @@
 // of the ISC license. See the LICENSE file for details.
 
 /**
- * @summary Some first test link
+ * Some first test link
+ * @link ../testRoot.ts
  */
 export default (test: string): string => test;

packages/dev/src/test2/bar.ts

@@ -2,14 +2,6 @@
 // This software may be modified and distributed under the terms
 // of the ISC license. See the LICENSE file for details.
 
-/**
- * @name bar
- * @signature bar (never: number, something: string): boolean
- * @summary This is the summary for bar
- * @description
- * This is the description with another line
- * @example
- * const bar = require('./bar');
- *
- * bar();
- */
+export default function bar () {
+  console.log('hello world');
+}

packages/dev/src/test2/index.ts

@@ -2,6 +2,8 @@
 // This software may be modified and distributed under the terms
 // of the ISC license. See the LICENSE file for details.
 
-/**
- * @summary Some second test link
- */
+import bar from './bar';
+
+export {
+  bar
+};

packages/dev/src/testRoot.ts

@@ -5,15 +5,13 @@
 import * as pkg from '../package.json';
 
 /**
- * @name test
- * @signature test (): boolean
- * @summary This is the summary for test, a root file
- * @description
  * This is the description with another line
- * @example
+ *
+ * ```
  * const test = require('./test');
  *
  * test(); // => nothing
+ * ```
  */
 export function test (): void {
   console.log(pkg.version);