Merge pull request #430 from 0xProject/0x.js/updateTypeDoc

Upgrade TypeDoc Dep & Add Missing @0xproject/types To Docs

11 files changed, 127 insertions, 65 deletions

diff --git a/packages/0x.js/package.json b/packages/0x.js/package.json
index 98b0981d4..e129fcc1d 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 $PROJECT_DIR",
+        "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'",
@@ -73,7 +73,7 @@
         "source-map-support": "^0.5.0",
         "truffle-hdwallet-provider": "^0.0.3",
         "tslint": "5.8.0",
-        "typedoc": "~0.8.0",
+        "typedoc": "0xProject/typedoc",
         "types-bn": "^0.0.1",
         "typescript": "2.7.1",
         "web3-provider-engine": "^13.0.1",
diff --git a/packages/0x.js/scripts/postpublish.js b/packages/0x.js/scripts/postpublish.js
index 7cbabd8f6..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 + ' PROJECT_DIR=' + __dirname + '/.. 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 b48c23851..f0ba55205 100644
--- a/packages/0x.js/scripts/stagedocs.js
+++ b/packages/0x.js/scripts/stagedocs.js
@@ -1,24 +1,31 @@
 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 + ' PROJECT_DIR=' + __dirname + '/.. yarn docs:json', {
+execAsync('JSON_FILE_PATH=' + jsonFilePath + ' PROJECT_FILES="' + projectFiles + '" yarn docs:json', {
     cwd,
 })
-.then(function(result) {
-    if (result.stderr !== '') {
-        throw new Error(result.stderr);
-    }
-    const fileName = 'v' + version + '.json';
-    const s3Url = S3BucketPath + fileName;
-    return execAsync('S3_URL=' + s3Url + ' yarn upload_docs_json', {
-        cwd,
+    .then(function(result) {
+        if (result.stderr !== '') {
+            throw new Error(result.stderr);
+        }
+        const fileName = 'v' + version + '.json';
+        const s3Url = S3BucketPath + fileName;
+        return execAsync('S3_URL=' + s3Url + ' yarn upload_docs_json', {
+            cwd,
+        });
+    })
+    .catch(function(err) {
+        console.log(err);
     });
-})
-.catch(function(err) {
-    console.log(err);
-});
diff --git a/packages/0x.js/src/index.ts b/packages/0x.js/src/index.ts
index 161945443..9879bbb56 100644
--- a/packages/0x.js/src/index.ts
+++ b/packages/0x.js/src/index.ts
@@ -34,6 +34,7 @@ export {
     BlockParam,
     ContractEventArg,
     LogWithDecodedArgs,
+    TransactionReceipt,
     TransactionReceiptWithDecodedLogs,
 } from '@0xproject/types';
 
@@ -58,5 +59,3 @@ export {
     ExchangeContractEventArgs,
     ExchangeEvents,
 } from './contract_wrappers/generated/exchange';
-
-export { TransactionReceipt } from '@0xproject/types';
diff --git a/packages/connect/package.json b/packages/connect/package.json
index 059d0efad..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 $PROJECT_DIR",
+        "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 869bad099..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 + ' PROJECT_DIR=' + __dirname + '/.. 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 868112a37..58272ab86 100644
--- a/packages/connect/scripts/stagedocs.js
+++ b/packages/connect/scripts/stagedocs.js
@@ -1,24 +1,30 @@
 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 + ' PROJECT_DIR=' + __dirname + '/.. yarn docs:json', {
+execAsync('JSON_FILE_PATH=' + jsonFilePath + ' PROJECT_FILES="' + projectFiles + '" yarn docs:json', {
     cwd,
 })
-.then(function(result) {
-    if (result.stderr !== '') {
-        throw new Error(result.stderr);
-    }
-    const fileName = 'v' + version + '.json';
-    const s3Url = S3BucketPath + fileName;
-    return execAsync('S3_URL=' + s3Url + ' yarn upload_docs_json', {
-        cwd,
+    .then(function(result) {
+        if (result.stderr !== '') {
+            throw new Error(result.stderr);
+        }
+        const fileName = 'v' + version + '.json';
+        const s3Url = S3BucketPath + fileName;
+        return execAsync('S3_URL=' + s3Url + ' yarn upload_docs_json', {
+            cwd,
+        });
+    })
+    .catch(function(err) {
+        console.log(err);
     });
-})
-.catch(function(err) {
-    console.log(err);
-});
diff --git a/packages/website/ts/containers/zero_ex_js_documentation.ts b/packages/website/ts/containers/zero_ex_js_documentation.ts
index a9d3249ee..d0d697e70 100644
--- a/packages/website/ts/containers/zero_ex_js_documentation.ts
+++ b/packages/website/ts/containers/zero_ex_js_documentation.ts
@@ -102,6 +102,7 @@ const docsInfoConfig: DocsInfoConfig = {
         'ApprovalContractEventArgs',
         'TokenContractEventArgs',
         'ZeroExConfig',
+        'TransactionReceipt',
         'TransactionReceiptWithDecodedLogs',
         'LogWithDecodedArgs',
         'EtherTokenEvents',
@@ -124,17 +125,33 @@ const docsInfoConfig: DocsInfoConfig = {
         'FilterObject',
     ],
     sectionNameToModulePath: {
-        [zeroExJsDocSections.zeroEx]: ['"src/0x"'],
-        [zeroExJsDocSections.exchange]: ['"src/contract_wrappers/exchange_wrapper"'],
-        [zeroExJsDocSections.tokenRegistry]: ['"src/contract_wrappers/token_registry_wrapper"'],
-        [zeroExJsDocSections.token]: ['"src/contract_wrappers/token_wrapper"'],
-        [zeroExJsDocSections.etherToken]: ['"src/contract_wrappers/ether_token_wrapper"'],
+        [zeroExJsDocSections.zeroEx]: ['"0x.js/src/0x"', '"src/0x"'],
+        [zeroExJsDocSections.exchange]: [
+            '"0x.js/src/contract_wrappers/exchange_wrapper"',
+            '"src/contract_wrappers/exchange_wrapper"',
+        ],
+        [zeroExJsDocSections.tokenRegistry]: [
+            '"0x.js/src/contract_wrappers/token_registry_wrapper"',
+            '"src/contract_wrappers/token_registry_wrapper"',
+        ],
+        [zeroExJsDocSections.token]: [
+            '"0x.js/src/contract_wrappers/token_wrapper"',
+            '"src/contract_wrappers/token_wrapper"',
+        ],
+        [zeroExJsDocSections.etherToken]: [
+            '"0x.js/src/contract_wrappers/ether_token_wrapper"',
+            '"src/contract_wrappers/ether_token_wrapper"',
+        ],
         [zeroExJsDocSections.proxy]: [
-            '"src/contract_wrappers/proxy_wrapper"',
+            '"0x.js/src/contract_wrappers/proxy_wrapper"',
+            '"0x.js/src/contract_wrappers/token_transfer_proxy_wrapper"',
             '"src/contract_wrappers/token_transfer_proxy_wrapper"',
         ],
-        [zeroExJsDocSections.orderWatcher]: ['"src/order_watcher/order_state_watcher"'],
-        [zeroExJsDocSections.types]: ['"src/types"'],
+        [zeroExJsDocSections.orderWatcher]: [
+            '"0x.js/src/order_watcher/order_state_watcher"',
+            '"src/order_watcher/order_state_watcher"',
+        ],
+        [zeroExJsDocSections.types]: ['"0x.js/src/types"', '"src/types"', '"types/src/index"'],
     },
     menuSubsectionToVersionWhenIntroduced: {
         [zeroExJsDocSections.etherToken]: '0.7.1',
diff --git a/packages/website/ts/pages/documentation/type_definition.tsx b/packages/website/ts/pages/documentation/type_definition.tsx
index d46eec76c..02bf63258 100644
--- a/packages/website/ts/pages/documentation/type_definition.tsx
+++ b/packages/website/ts/pages/documentation/type_definition.tsx
@@ -113,7 +113,9 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
                         <code className="hljs">{codeSnippet}</code>
                     </pre>
                 </div>
-                {customType.comment && <Comment comment={customType.comment} className="py2" />}
+                <div style={{ maxWidth: 620 }}>
+                    {customType.comment && <Comment comment={customType.comment} className="py2" />}
+                </div>
             </div>
         );
     }
diff --git a/packages/website/ts/types.ts b/packages/website/ts/types.ts
index f0db537e6..28663270e 100644
--- a/packages/website/ts/types.ts
+++ b/packages/website/ts/types.ts
@@ -308,7 +308,7 @@ export interface TypeDocNode {
     returns?: string;
     declaration: TypeDocNode;
     flags?: TypeDocFlags;
-    indexSignature?: TypeDocNode[];
+    indexSignature?: TypeDocNode | TypeDocNode[]; // TypeDocNode in TypeDoc <V0.9.0, TypeDocNode[] in >V0.9.0
     signatures?: TypeDocNode[];
     parameters?: TypeDocNode[];
     typeParameter?: TypeDocNode[];
diff --git a/packages/website/ts/utils/typedoc_utils.ts b/packages/website/ts/utils/typedoc_utils.ts
index 992475911..ce7df4dbb 100644
--- a/packages/website/ts/utils/typedoc_utils.ts
+++ b/packages/website/ts/utils/typedoc_utils.ts
@@ -41,18 +41,17 @@ export const typeDocUtils = {
     isPrivateOrProtectedProperty(propertyName: string): boolean {
         return _.startsWith(propertyName, '_');
     },
-    getModuleDefinitionBySectionNameIfExists(
-        versionDocObj: TypeDocNode,
-        modulePaths: string[],
-    ): TypeDocNode | undefined {
-        const modules = versionDocObj.children;
-        for (const mod of modules) {
-            if (_.includes(modulePaths, mod.name)) {
-                const moduleWithName = mod;
-                return moduleWithName;
-            }
-        }
-        return undefined;
+    getModuleDefinitionsBySectionName(versionDocObj: TypeDocNode, configModulePaths: string[]): TypeDocNode[] {
+        const moduleDefinitions: TypeDocNode[] = [];
+        const jsonModules = versionDocObj.children;
+        _.each(jsonModules, jsonMod => {
+            _.each(configModulePaths, configModulePath => {
+                if (_.includes(configModulePath, jsonMod.name)) {
+                    moduleDefinitions.push(jsonMod);
+                }
+            });
+        });
+        return moduleDefinitions;
     },
     convertToDocAgnosticFormat(typeDocJson: TypeDocNode, docsInfo: DocsInfo): DocAgnosticFormat {
         const subMenus = _.values(docsInfo.getMenu());
@@ -63,12 +62,23 @@ export const typeDocUtils = {
             if (_.isUndefined(modulePathsIfExists)) {
                 return; // no-op
             }
-            const packageDefinitionIfExists = typeDocUtils.getModuleDefinitionBySectionNameIfExists(
-                typeDocJson,
-                modulePathsIfExists,
-            );
-            if (_.isUndefined(packageDefinitionIfExists)) {
+            const packageDefinitions = typeDocUtils.getModuleDefinitionsBySectionName(typeDocJson, modulePathsIfExists);
+            let packageDefinitionWithMergedChildren;
+            if (_.isEmpty(packageDefinitions)) {
                 return; // no-op
+            } else if (packageDefinitions.length === 1) {
+                packageDefinitionWithMergedChildren = packageDefinitions[0];
+            } else {
+                // HACK: For now, if there are two modules to display in a single section,
+                // we simply concat the children. This works for our limited use-case where
+                // we want to display types stored in two files under a single section
+                packageDefinitionWithMergedChildren = packageDefinitions[0];
+                for (let i = 1; i < packageDefinitions.length; i++) {
+                    packageDefinitionWithMergedChildren.children = [
+                        ...packageDefinitionWithMergedChildren.children,
+                        ...packageDefinitions[i].children,
+                    ];
+                }
             }
 
             // Since the `types.ts` file is the only file that does not export a module/class but
@@ -77,10 +87,10 @@ export const typeDocUtils = {
             let entities;
             let packageComment = '';
             if (sectionName === docsInfo.sections.types) {
-                entities = packageDefinitionIfExists.children;
+                entities = packageDefinitionWithMergedChildren.children;
             } else {
-                entities = packageDefinitionIfExists.children[0].children;
-                const commentObj = packageDefinitionIfExists.children[0].comment;
+                entities = packageDefinitionWithMergedChildren.children[0].children;
+                const commentObj = packageDefinitionWithMergedChildren.children[0].comment;
                 packageComment = !_.isUndefined(commentObj) ? commentObj.shortText : packageComment;
             }
 
@@ -170,8 +180,16 @@ export const typeDocUtils = {
         const methodIfExists = !_.isUndefined(entity.declaration)
             ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId)
             : undefined;
-        const indexSignatureIfExists = !_.isUndefined(entity.indexSignature)
-            ? typeDocUtils._convertIndexSignature(entity.indexSignature[0], sections, sectionName, docId)
+        const doesIndexSignatureExist = !_.isUndefined(entity.indexSignature);
+        const isIndexSignatureArray = _.isArray(entity.indexSignature);
+        // HACK: TypeDoc Versions <0.9.0 indexSignature is of type TypeDocNode[]
+        // Versions >0.9.0 have it as type TypeDocNode
+        const indexSignature =
+            doesIndexSignatureExist && isIndexSignatureArray
+                ? (entity.indexSignature as TypeDocNode[])[0]
+                : (entity.indexSignature as TypeDocNode);
+        const indexSignatureIfExists = doesIndexSignatureExist
+            ? typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId)
             : undefined;
         const commentIfExists =
             !_.isUndefined(entity.comment) && !_.isUndefined(entity.comment.shortText)