Merge branch '0x.js/updateTypeDoc' into extractDocs

* 0x.js/updateTypeDoc:
  Fix comments
  Add comments
  Don't need any external packages for 0x connect docs yet
  Instead of adding `@0xproject/types` to tsconfig.json, let's only add it when calling TypeDoc
  Fix styling
  Make prettier ignore postpublish_utils
  Update yarn.lock

10 files changed, 68 insertions, 55 deletions

diff --git a/.prettierignore b/.prettierignore
index 385c15654..5b8003c95 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -2,3 +2,4 @@ lib
 .nyc_output
 /packages/contracts/src/artifacts
 package.json
+scripts/postpublish_utils.js
diff --git a/packages/0x.js/package.json b/packages/0x.js/package.json
index e51ad5def..85f865192 100644
--- a/packages/0x.js/package.json
+++ b/packages/0x.js/package.json
@@ -15,7 +15,7 @@
         "build:watch": "tsc -w",
         "prebuild": "run-s clean generate_contract_wrappers",
         "build": "run-p build:umd:prod build:commonjs; exit 0;",
-        "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --json $JSON_FILE_PATH",
+        "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --json $JSON_FILE_PATH $PROJECT_FILES",
         "upload_docs_json": "aws s3 cp generated_docs/index.json $S3_URL --profile 0xproject --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json",
         "generate_contract_wrappers": "node ../abi-gen/lib/index.js --abis 'src/artifacts/@(Exchange|Token|TokenTransferProxy|EtherToken|TokenRegistry|DummyToken).json' --template ../contract_templates/contract.handlebars --partials '../contract_templates/partials/**/*.handlebars' --output src/contract_wrappers/generated --backend ethers && prettier --write 'src/contract_wrappers/generated/**.ts'",
         "lint": "tslint --project . 'src/**/*.ts' 'test/**/*.ts'",
diff --git a/packages/0x.js/scripts/postpublish.js b/packages/0x.js/scripts/postpublish.js
index de2c5158e..1a9ab73ea 100644
--- a/packages/0x.js/scripts/postpublish.js
+++ b/packages/0x.js/scripts/postpublish.js
@@ -1,9 +1,16 @@
 const execAsync = require('async-child-process').execAsync;
 const postpublish_utils = require('../../../scripts/postpublish_utils');
 const packageJSON = require('../package.json');
+const tsConfig = require('../tsconfig.json');
 
 const cwd = __dirname + '/..';
 const subPackageName = packageJSON.name;
+// Include any external packages that are part of the 0x.js public interface
+// to this array so that TypeDoc picks it up and adds it to the Docs JSON
+// So far, we only have @0xproject/types as part of 0x.js's public interface.
+const fileIncludes = [...tsConfig.include, '../types/src/index.ts'];
+const fileIncludesAdjusted = postpublish_utils.adjustFileIncludePaths(fileIncludes, __dirname);
+const projectFiles = fileIncludesAdjusted.join(' ');
 const S3BucketPath = 's3://0xjs-docs-jsons/';
 
 let tag;
@@ -20,7 +27,7 @@ postpublish_utils
     .then(function(release) {
         console.log('POSTPUBLISH: Release successful, generating docs...');
         const jsonFilePath = __dirname + '/../' + postpublish_utils.generatedDocsDirectoryName + '/index.json';
-        return execAsync('JSON_FILE_PATH=' + jsonFilePath + ' yarn docs:json', {
+        return execAsync('JSON_FILE_PATH=' + jsonFilePath + ' PROJECT_FILES="' + projectFiles + '" yarn docs:json', {
             cwd,
         });
     })
diff --git a/packages/0x.js/scripts/stagedocs.js b/packages/0x.js/scripts/stagedocs.js
index c936757bf..f0ba55205 100644
--- a/packages/0x.js/scripts/stagedocs.js
+++ b/packages/0x.js/scripts/stagedocs.js
@@ -1,12 +1,19 @@
 const execAsync = require('async-child-process').execAsync;
 const postpublish_utils = require('../../../scripts/postpublish_utils');
+const tsConfig = require('../tsconfig.json');
 
 const cwd = __dirname + '/..';
 const S3BucketPath = 's3://staging-0xjs-docs-jsons/';
+// Include any external packages that are part of the 0x.js public interface
+// to this array so that TypeDoc picks it up and adds it to the Docs JSON
+// So far, we only have @0xproject/types as part of 0x.js's public interface.
+const fileIncludes = [...tsConfig.include, '../types/src/index.ts'];
+const fileIncludesAdjusted = postpublish_utils.adjustFileIncludePaths(fileIncludes, __dirname);
+const projectFiles = fileIncludesAdjusted.join(' ');
 const jsonFilePath = __dirname + '/../' + postpublish_utils.generatedDocsDirectoryName + '/index.json';
 const version = process.env.DOCS_VERSION;
 
-execAsync('JSON_FILE_PATH=' + jsonFilePath + ' yarn docs:json', {
+execAsync('JSON_FILE_PATH=' + jsonFilePath + ' PROJECT_FILES="' + projectFiles + '" yarn docs:json', {
     cwd,
 })
     .then(function(result) {
diff --git a/packages/0x.js/tsconfig.json b/packages/0x.js/tsconfig.json
index 70ef5a624..a6b5c71c2 100644
--- a/packages/0x.js/tsconfig.json
+++ b/packages/0x.js/tsconfig.json
@@ -7,7 +7,6 @@
     "include": [
         "./src/**/*",
         "./test/**/*",
-        "../types/src/index.ts",
         "../../node_modules/types-bn/index.d.ts",
         "../../node_modules/types-ethereumjs-util/index.d.ts",
         "../../node_modules/ethers-typescript-typings/index.d.ts",
diff --git a/packages/connect/package.json b/packages/connect/package.json
index 9cc41a10d..5ee2dcdcf 100644
--- a/packages/connect/package.json
+++ b/packages/connect/package.json
@@ -15,7 +15,7 @@
         "build:watch": "tsc -w",
         "build": "tsc",
         "clean": "shx rm -rf _bundles lib test_temp",
-        "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --json $JSON_FILE_PATH",
+        "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --json $JSON_FILE_PATH $PROJECT_FILES",
         "upload_docs_json": "aws s3 cp generated_docs/index.json $S3_URL --profile 0xproject --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json",
         "copy_test_fixtures": "copyfiles -u 2 './test/fixtures/**/*.json' ./lib/test/fixtures",
         "lint": "tslint --project . 'src/**/*.ts' 'test/**/*.ts'",
diff --git a/packages/connect/scripts/postpublish.js b/packages/connect/scripts/postpublish.js
index 01c349cb8..e447615f9 100644
--- a/packages/connect/scripts/postpublish.js
+++ b/packages/connect/scripts/postpublish.js
@@ -1,10 +1,16 @@
 const execAsync = require('async-child-process').execAsync;
 const postpublish_utils = require('../../../scripts/postpublish_utils');
 const packageJSON = require('../package.json');
+const tsConfig = require('../tsconfig.json');
 
 const cwd = __dirname + '/..';
 const subPackageName = packageJSON.name;
 const S3BucketPath = 's3://connect-docs-jsons/';
+// Include any external packages that are part of the @0xproject/connect public interface
+// to this array so that TypeDoc picks it up and adds it to the Docs JSON
+const fileIncludes = [...tsConfig.include];
+const fileIncludesAdjusted = postpublish_utils.adjustFileIncludePaths(fileIncludes, __dirname);
+const projectFiles = fileIncludesAdjusted.join(' ');
 
 let tag;
 let version;
@@ -19,7 +25,7 @@ postpublish_utils
     .then(function(release) {
         console.log('POSTPUBLISH: Release successful, generating docs...');
         const jsonFilePath = __dirname + '/../' + postpublish_utils.generatedDocsDirectoryName + '/index.json';
-        return execAsync('JSON_FILE_PATH=' + jsonFilePath + ' yarn docs:json', {
+        return execAsync('JSON_FILE_PATH=' + jsonFilePath + ' PROJECT_FILES="' + projectFiles + '" yarn docs:json', {
             cwd,
         });
     })
diff --git a/packages/connect/scripts/stagedocs.js b/packages/connect/scripts/stagedocs.js
index c8f44d90f..58272ab86 100644
--- a/packages/connect/scripts/stagedocs.js
+++ b/packages/connect/scripts/stagedocs.js
@@ -1,12 +1,18 @@
 const execAsync = require('async-child-process').execAsync;
 const postpublish_utils = require('../../../scripts/postpublish_utils');
+const tsConfig = require('../tsconfig.json');
 
 const cwd = __dirname + '/..';
 const S3BucketPath = 's3://staging-connect-docs-jsons/';
 const jsonFilePath = __dirname + '/../' + postpublish_utils.generatedDocsDirectoryName + '/index.json';
 const version = process.env.DOCS_VERSION;
+// Include any external packages that are part of the @0xproject/connect public interface
+// to this array so that TypeDoc picks it up and adds it to the Docs JSON
+const fileIncludes = [...tsConfig.include];
+const fileIncludesAdjusted = postpublish_utils.adjustFileIncludePaths(fileIncludes, __dirname);
+const projectFiles = fileIncludesAdjusted.join(' ');
 
-execAsync('JSON_FILE_PATH=' + jsonFilePath + ' yarn docs:json', {
+execAsync('JSON_FILE_PATH=' + jsonFilePath + ' PROJECT_FILES="' + projectFiles + '" yarn docs:json', {
     cwd,
 })
     .then(function(result) {
diff --git a/scripts/postpublish_utils.js b/scripts/postpublish_utils.js
index 7ce01189c..6f990eb5e 100644
--- a/scripts/postpublish_utils.js
+++ b/scripts/postpublish_utils.js
@@ -1,3 +1,4 @@
+const _ = require('lodash');
 const execAsync = require('async-child-process').execAsync;
 const semverSort = require('semver-sort');
 const publishRelease = require('publish-release');
@@ -11,23 +12,22 @@ module.exports = {
     getLatestTagAndVersionAsync: function(subPackageName) {
         const subPackagePrefix = subPackageName + '@';
         const gitTagsCommand = 'git tag -l "' + subPackagePrefix + '*"';
-        return execAsync(gitTagsCommand)
-            .then(function(result) {
-                if (result.stderr !== '') {
-                    throw new Error(result.stderr);
-                }
-                const tags = result.stdout.trim().split('\n');
-                const versions = tags.map(function(tag) {
-                    return tag.slice(subPackagePrefix.length);
-                });
-                const sortedVersions = semverSort.desc(versions);
-                const latestVersion = sortedVersions[0];
-                const latestTag = subPackagePrefix + latestVersion;
-                return {
-                    tag: latestTag,
-                    version: latestVersion
-                };
+        return execAsync(gitTagsCommand).then(function(result) {
+            if (result.stderr !== '') {
+                throw new Error(result.stderr);
+            }
+            const tags = result.stdout.trim().split('\n');
+            const versions = tags.map(function(tag) {
+                return tag.slice(subPackagePrefix.length);
             });
+            const sortedVersions = semverSort.desc(versions);
+            const latestVersion = sortedVersions[0];
+            const latestTag = subPackagePrefix + latestVersion;
+            return {
+                tag: latestTag,
+                version: latestVersion,
+            };
+        });
     },
     publishReleaseNotesAsync: function(tag, releaseName, assets) {
         console.log('POSTPUBLISH: Releasing ', releaseName, '...');
@@ -43,7 +43,7 @@ module.exports = {
             reuseRelease: true,
             reuseDraftOnly: false,
             assets: assets,
-         });
+        });
     },
     getReleaseName(subPackageName, version) {
         const releaseName = subPackageName + ' v' + version;
@@ -51,14 +51,26 @@ module.exports = {
     },
     standardPostPublishAsync: function(subPackageName) {
         return this.getLatestTagAndVersionAsync(subPackageName)
-            .then(function(result) {
-                const releaseName = this.getReleaseName(subPackageName, result.version);
-                const assets = [];
-                return this.publishReleaseNotesAsync(result.tag, releaseName, assets);
-            }.bind(this))
+            .then(
+                function(result) {
+                    const releaseName = this.getReleaseName(subPackageName, result.version);
+                    const assets = [];
+                    return this.publishReleaseNotesAsync(result.tag, releaseName, assets);
+                }.bind(this)
+            )
             .catch(function(err) {
                 throw err;
             });
     },
+    adjustFileIncludePaths: function(fileIncludes, cwd) {
+        const fileIncludesAdjusted = _.map(fileIncludes, fileInclude => {
+            if (_.startsWith(fileInclude, '../')) {
+                return cwd + '/../' + fileInclude;
+            } else if (_.startsWith('./')) {
+                return cwd + '/../' + fileInclude;
+            }
+        });
+        return fileIncludesAdjusted;
+    },
     generatedDocsDirectoryName,
 };
diff --git a/yarn.lock b/yarn.lock
index e3b20ba33..a1e35e3f1 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1995,10 +1995,6 @@ commander@2.11.0:
   version "2.11.0"
   resolved "https://registry.yarnpkg.com/commander/-/commander-2.11.0.tgz#157152fd1e7a6c8d98a5b715cf376df928004563"
 
-commander@^2.12.1:
-  version "2.14.1"
-  resolved "https://registry.yarnpkg.com/commander/-/commander-2.14.1.tgz#2235123e37af8ca3c65df45b026dbd357b01b9aa"
-
 commander@^2.9.0:
   version "2.13.0"
   resolved "https://registry.yarnpkg.com/commander/-/commander-2.13.0.tgz#6964bca67685df7c1f1430c584f07d7597885b9c"
@@ -5057,7 +5053,7 @@ js-tokens@^3.0.0, js-tokens@^3.0.2:
   version "3.0.2"
   resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-3.0.2.tgz#9866df395102130e38f7f996bceb65443209c25b"
 
-js-yaml@^3.6.1, js-yaml@^3.7.0:
+js-yaml@^3.6.1:
   version "3.10.0"
   resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.10.0.tgz#2e78441646bd4682e963f22b6e92823c309c62dc"
   dependencies:
@@ -9133,10 +9129,6 @@ tslib@^1.0.0, tslib@^1.7.1, tslib@^1.8.1:
   version "1.8.1"
   resolved "https://registry.yarnpkg.com/tslib/-/tslib-1.8.1.tgz#6946af2d1d651a7b1863b531d6e5afa41aa44eac"
 
-tslib@^1.8.0:
-  version "1.9.0"
-  resolved "https://registry.yarnpkg.com/tslib/-/tslib-1.9.0.tgz#e37a86fda8cbbaf23a057f473c9f4dc64e5fc2e8"
-
 tslint-config-0xproject@^0.0.2:
   version "0.0.2"
   resolved "https://registry.yarnpkg.com/tslint-config-0xproject/-/tslint-config-0xproject-0.0.2.tgz#39901e0c0b3e9388f00092a28b90c015395d5bba"
@@ -9173,23 +9165,6 @@ tslint@5.8.0:
     tslib "^1.7.1"
     tsutils "^2.12.1"
 
-tslint@^5.9.1:
-  version "5.9.1"
-  resolved "https://registry.yarnpkg.com/tslint/-/tslint-5.9.1.tgz#1255f87a3ff57eb0b0e1f0e610a8b4748046c9ae"
-  dependencies:
-    babel-code-frame "^6.22.0"
-    builtin-modules "^1.1.1"
-    chalk "^2.3.0"
-    commander "^2.12.1"
-    diff "^3.2.0"
-    glob "^7.1.1"
-    js-yaml "^3.7.0"
-    minimatch "^3.0.4"
-    resolve "^1.3.2"
-    semver "^5.3.0"
-    tslib "^1.8.0"
-    tsutils "^2.12.1"
-
 tsutils@^1.4.0:
   version "1.9.1"
   resolved "https://registry.yarnpkg.com/tsutils/-/tsutils-1.9.1.tgz#b9f9ab44e55af9681831d5f28d0aeeaf5c750cb0"