Refactor doc generation script to only generate MD docs and to have them reflect what is exported in their respective index.ts files

package.json

@@ -42,8 +42,7 @@
         "rebuild:no_website": "run-s clean build:no_website",
         "test": "wsrun test $PKG --fast-exit --serial --exclude-missing",
         "test:contracts": "wsrun test -p ${npm_package_config_contractsPackages} -c --fast-exit --serial --exclude-missing",
-        "generate_doc": "node ./packages/monorepo-scripts/lib/doc_generate_and_upload.js",
+        "generate_doc": "node ./packages/monorepo-scripts/lib/doc_generate.js",
-        "generate_md_docs": "wsrun docs:md --exclude-missing",
         "upload_md_docs": "wsrun s3:sync_md_docs --exclude-missing",
         "diff_md_docs:ci": "wsrun diff_docs --exclude-missing",
         "test:generate_docs:circleci": "for i in ${npm_package_config_packagesWithDocPages}; do yarn generate_doc --package $i --shouldUpload false --isStaging true || break -1; done;",

packages/0x.js/package.json

@@ -27,7 +27,10 @@
         "clean": "shx rm -rf _bundles lib test_temp src/generated_contract_wrappers generated_docs",
         "build:umd:prod": "NODE_ENV=production node --max_old_space_size=8192 ../../node_modules/.bin/webpack --mode production",
         "build:commonjs": "tsc -b",
-        "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
+        "diff_docs": "git diff --exit-code ./docs",
+        "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:json": "typedoc --excludePrivate --excludeExternals --excludePrivate --excludeProtected --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {
         "postpublish": {
@@ -43,6 +46,7 @@
     },
     "license": "Apache-2.0",
     "devDependencies": {
+        "@0x/ts-doc-gen": "^0.0.17",
         "@0x/contract-addresses": "^3.1.0",
         "@0x/dev-utils": "^2.3.1",
         "@0x/migrations": "^4.3.0",

packages/asset-buyer/package.json

@@ -21,7 +21,7 @@
         "clean": "shx rm -rf lib test_temp",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/asset-swapper/package.json

@@ -21,7 +21,7 @@
         "clean": "shx rm -rf lib test_temp",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/connect/package.json

@@ -29,7 +29,7 @@
         "test:circleci": "yarn test:coverage",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/ethereum-types/package.json

@@ -15,7 +15,7 @@
         "fix": "tslint --fix --format stylish --project .",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/json-schemas/package.json

@@ -21,7 +21,7 @@
         "clean": "shx rm -rf lib test_temp generated_docs",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/migrations/package.json

@@ -19,7 +19,7 @@
         "script:migrate:v2:snapshot": "node ./lib/migrate_snapshot.js",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES",
         "build:snapshot": "rm -rf ${npm_package_config_snapshot_name} && yarn migrate:v2:snapshot && zip -r \"${npm_package_config_snapshot_name}-${npm_package_version}.zip\" ${npm_package_config_snapshot_name}",
         "build:snapshot:docker": "docker build --tag ${npm_package_config_docker_snapshot_name}:${npm_package_version} --tag ${npm_package_config_docker_snapshot_name}:latest .",

packages/monorepo-scripts/package.json

@@ -20,7 +20,7 @@
         "script:prepublish_checks": "node ./lib/prepublish_checks.js",
         "script:publish": "IS_DRY_RUN=true node ./lib/publish.js",
         "script:find_unused_deps": "node ./lib/find_unused_dependencies.js",
-        "script:doc_generate_and_upload": "node ./lib/doc_generate_and_upload.js",
+        "script:doc_generate": "node ./lib/doc_generate.js",
         "script:publish_release_notes": "node ./lib/publish_release_notes.js"
     },
     "repository": {

packages/monorepo-scripts/src/doc_gen_configs.ts

@@ -29,30 +29,6 @@ export const docGenConfigs: DocGenConfigs = {
         Buy: 'https://github.com/0xProject/0x-monorepo/blob/development/packages/types/src/index.ts',
         Sell: 'https://github.com/0xProject/0x-monorepo/blob/development/packages/types/src/index.ts',
     },
-    // If a 0x package re-exports an external package, we should add a link to it's exported items here
-    EXTERNAL_EXPORT_TO_LINK: {
-        Web3ProviderEngine: 'https://www.npmjs.com/package/web3-provider-engine',
-        BigNumber: 'https://www.npmjs.com/package/bignumber.js',
-        Schema: 'https://github.com/tdegrunt/jsonschema/blob/v1.2.4/lib/index.d.ts#L49',
-        ValidatorResult: 'https://github.com/tdegrunt/jsonschema/blob/v1.2.4/lib/helpers.js#L31',
-    },
-    // Sometimes we want to hide a constructor from rendering in our docs. An example is when our library has a
-    // factory method which instantiates an instance of a class, but we don't want users instantiating it themselves
-    // and getting confused. Any class name in this list will not have it's constructor rendered in our docs.
-    CLASSES_WITH_HIDDEN_CONSTRUCTORS: [
-        'SwapQuoter',
-        'CoordinatorWrapper',
-        'DutchAuctionWrapper',
-        'ERC20ProxyWrapper',
-        'ERC20TokenWrapper',
-        'ERC721ProxyWrapper',
-        'ERC721TokenWrapper',
-        'EtherTokenWrapper',
-        'ExchangeWrapper',
-        'ForwarderWrapper',
-        'OrderValidatorWrapper',
-        'TransactionEncoder',
-    ],
     // Some types are not explicitly part of the public interface like params, return values, etc... But we still
     // want them exported. E.g error enum types that can be thrown by methods. These must be manually added to this
     // config

packages/monorepo-scripts/src/doc_generate.ts

@@ -0,0 +1,24 @@
+import * as yargs from 'yargs';
+
+import { DocGenerateUtils } from './utils/doc_generate_utils';
+import { utils } from './utils/utils';
+
+const args = yargs
+    .option('package', {
+        describe: 'Monorepo sub-package for which to generate DocJSON',
+        type: 'string',
+        demandOption: true,
+    })
+    .example("$0 --package '0x.js'", 'Full usage example').argv;
+
+(async () => {
+    const packageName = args.package;
+
+    const docGenerateAndUploadUtils = new DocGenerateUtils(packageName);
+    await docGenerateAndUploadUtils.generateAndUploadDocsAsync();
+
+    process.exit(0);
+})().catch(err => {
+    utils.log(err);
+    process.exit(1);
+});

packages/monorepo-scripts/src/doc_generate_and_upload.ts

@@ -1,37 +0,0 @@
-import * as yargs from 'yargs';
-
-import { DocGenerateAndUploadUtils } from './utils/doc_generate_and_upload_utils';
-import { utils } from './utils/utils';
-
-const args = yargs
-    .option('package', {
-        describe: 'Monorepo sub-package for which to generate DocJSON',
-        type: 'string',
-        demandOption: true,
-    })
-    .option('isStaging', {
-        describe: 'Whether we wish to publish docs to staging or production',
-        type: 'boolean',
-        demandOption: true,
-    })
-    .option('shouldUpload', {
-        describe: 'Whether we wish to upload the docs to S3 or not',
-        type: 'boolean',
-        demandOption: false,
-        default: true,
-    })
-    .example("$0 --package '0x.js' --isStaging true", 'Full usage example').argv;
-
-(async () => {
-    const packageName = args.package;
-    const isStaging = args.isStaging;
-    const shouldUploadDocs = args.shouldUpload;
-
-    const docGenerateAndUploadUtils = new DocGenerateAndUploadUtils(packageName, isStaging, shouldUploadDocs);
-    await docGenerateAndUploadUtils.generateAndUploadDocsAsync();
-
-    process.exit(0);
-})().catch(err => {
-    utils.log(err);
-    process.exit(1);
-});

packages/monorepo-scripts/src/publish.ts

@@ -19,7 +19,7 @@ import { Package, PackageToNextVersion, VersionChangelog } from './types';
 import { changelogUtils } from './utils/changelog_utils';
 import { configs } from './utils/configs';
 import { alertDiscordAsync } from './utils/discord';
-import { DocGenerateAndUploadUtils } from './utils/doc_generate_and_upload_utils';
+import { DocGenerateUtils } from './utils/doc_generate_utils';
 import { publishReleaseNotesAsync } from './utils/github_release_utils';
 import { utils } from './utils/utils';
 
@@ -50,7 +50,6 @@ async function confirmAsync(message: string): Promise<void> {
         await confirmAsync(
             'THIS IS NOT A TEST PUBLISH! You are about to publish one or more packages to npm. Are you sure you want to continue? (y/n)',
         );
-        await confirmDocPagesRenderAsync(packagesWithDocs);
     }
 
     // Update CHANGELOGs
@@ -72,7 +71,8 @@ async function confirmAsync(message: string): Promise<void> {
     });
 
     // Generate markdown docs for packages
-    await execAsync(`yarn generate_md_docs`, { cwd: constants.monorepoRootPath });
+    const isStaging = true;
+    await generateDocMDAsync(packagesWithDocs);
 
     // Push changelogs changes and markdown docs to Github
     if (!configs.IS_LOCAL_PUBLISH) {
@@ -92,10 +92,6 @@ async function confirmAsync(message: string): Promise<void> {
         // Publish docker images to DockerHub
         await publishImagesToDockerHubAsync(allPackagesToPublish);
 
-        const isStaging = false;
-        const shouldUploadDocs = true;
-        await generateAndUploadDocJsonsAsync(packagesWithDocs, isStaging, shouldUploadDocs);
-
         // Upload markdown docs to S3 bucket
         await execAsync(`yarn upload_md_docs`, { cwd: constants.monorepoRootPath });
     }
@@ -167,41 +163,14 @@ function getPackagesWithDocs(allUpdatedPackages: Package[]): Package[] {
     return updatedPackagesWithDocPages;
 }
 
-async function generateAndUploadDocJsonsAsync(
+async function generateDocMDAsync(packagesWithDocs: Package[]): Promise<void> {
-    packagesWithDocs: Package[],
-    isStaging: boolean,
-    shouldUploadDocs: boolean,
-): Promise<void> {
     for (const pkg of packagesWithDocs) {
         const nameWithoutPrefix = pkg.packageJson.name.replace('@0x/', '');
-        const docGenerateAndUploadUtils = new DocGenerateAndUploadUtils(nameWithoutPrefix, isStaging, shouldUploadDocs);
+        const docGenerateAndUploadUtils = new DocGenerateUtils(nameWithoutPrefix);
         await docGenerateAndUploadUtils.generateAndUploadDocsAsync();
     }
 }
 
-async function confirmDocPagesRenderAsync(packagesWithDocs: Package[]): Promise<void> {
-    // push docs to staging
-    utils.log("Upload all docJson's to S3 staging...");
-    const isStaging = true;
-    const shouldUploadDocs = true;
-    await generateAndUploadDocJsonsAsync(packagesWithDocs, isStaging, shouldUploadDocs);
-
-    // deploy website to staging
-    utils.log('Deploy website to staging...');
-    const pathToWebsite = `${constants.monorepoRootPath}/packages/website`;
-    await execAsync(`yarn deploy_staging`, { cwd: pathToWebsite });
-
-    _.each(packagesWithDocs, pkg => {
-        const name = pkg.packageJson.name;
-        const nameWithoutPrefix = _.startsWith(name, NPM_NAMESPACE) ? name.split('@0x/')[1] : name;
-        const link = `${constants.stagingWebsite}/docs/tools/${nameWithoutPrefix}`;
-        // tslint:disable-next-line:no-floating-promises
-        opn(link);
-    });
-
-    await confirmAsync('Do all the doc pages render? (y/n)');
-}
-
 async function pushChangelogsAndMDDocsToGithubAsync(): Promise<void> {
     await execAsync(`git add . --all`, { cwd: constants.monorepoRootPath });
     await execAsync(`git commit -m "Updated CHANGELOGS & MD docs"`, { cwd: constants.monorepoRootPath });

packages/monorepo-scripts/src/types.ts

@@ -44,8 +44,6 @@ export interface Package {
 export interface DocGenConfigs {
     DOC_JSON_VERSION: string;
     EXTERNAL_TYPE_TO_LINK: { [externalType: string]: string };
-    EXTERNAL_EXPORT_TO_LINK: { [externalExport: string]: string };
-    CLASSES_WITH_HIDDEN_CONSTRUCTORS: string[];
     IGNORED_EXCESSIVE_TYPES: string[];
     TYPES_ONLY_LIBRARIES: string[];
 }

packages/monorepo-scripts/src/utils/doc_generate_utils.ts

@@ -1,5 +1,5 @@
 import { PackageJSON } from '@0x/types';
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
 import * as _ from 'lodash';
 import * as path from 'path';
 import { exec as execAsync } from 'promisify-child-process';
@@ -11,9 +11,7 @@ import { ExportInfo, ExportNameToTypedocNames, ExportPathToExportedItems } from
 
 import { utils } from './utils';
 
-export class DocGenerateAndUploadUtils {
+export class DocGenerateUtils {
-    private readonly _isStaging: boolean;
-    private readonly _shouldUploadDocs: boolean;
     private readonly _packageName: string;
     private readonly _omitExports: string[];
     private readonly _packagePath: string;
@@ -36,10 +34,10 @@ export class DocGenerateAndUploadUtils {
         _.each(node, nodeValue => {
             if (_.isArray(nodeValue)) {
                 _.each(nodeValue, aNode => {
-                    updatedTypeNames = DocGenerateAndUploadUtils._getAllTypeNames(aNode, updatedTypeNames);
+                    updatedTypeNames = DocGenerateUtils._getAllTypeNames(aNode, updatedTypeNames);
                 });
             } else if (_.isObject(nodeValue)) {
-                updatedTypeNames = DocGenerateAndUploadUtils._getAllTypeNames(nodeValue, updatedTypeNames);
+                updatedTypeNames = DocGenerateUtils._getAllTypeNames(nodeValue, updatedTypeNames);
             }
         });
         return updatedTypeNames;
@@ -71,14 +69,14 @@ export class DocGenerateAndUploadUtils {
         _.each(node, (nodeValue, innerPropertyName) => {
             if (_.isArray(nodeValue)) {
                 _.each(nodeValue, aNode => {
-                    updatedReferenceNames = DocGenerateAndUploadUtils._getAllReferenceNames(
+                    updatedReferenceNames = DocGenerateUtils._getAllReferenceNames(
                         innerPropertyName,
                         aNode,
                         updatedReferenceNames,
                     );
                 });
             } else if (_.isObject(nodeValue)) {
-                updatedReferenceNames = DocGenerateAndUploadUtils._getAllReferenceNames(
+                updatedReferenceNames = DocGenerateUtils._getAllReferenceNames(
                     innerPropertyName,
                     nodeValue,
                     updatedReferenceNames,
@@ -161,10 +159,8 @@ export class DocGenerateAndUploadUtils {
         };
         return exportInfo;
     }
-    constructor(packageName: string, isStaging: boolean, shouldUploadDocs: boolean) {
+    constructor(packageName: string) {
-        this._isStaging = isStaging;
         this._packageName = packageName;
-        this._shouldUploadDocs = shouldUploadDocs;
         this._packagePath = `${constants.monorepoRootPath}/packages/${packageName}`;
 
         this._monoRepoPkgNameToPath = {};
@@ -181,7 +177,7 @@ export class DocGenerateAndUploadUtils {
         this._omitExports = _.get(this._packageJson, 'config.postpublish.docOmitExports', []);
 
         const indexPath = `${this._packagePath}/src/index.ts`;
-        const exportInfo = DocGenerateAndUploadUtils._getExportPathToExportedItems(indexPath, this._omitExports);
+        const exportInfo = DocGenerateUtils._getExportPathToExportedItems(indexPath, this._omitExports);
         this._exportPathToExportedItems = exportInfo.exportPathToExportedItems;
         this._exportPathOrder = exportInfo.exportPathOrder;
     }
@@ -198,8 +194,10 @@ export class DocGenerateAndUploadUtils {
             typeDocExtraFileIncludes.push(globalTypeDefinitionsPath);
         }
 
-        utils.log(`GENERATE_UPLOAD_DOCS: Generating Typedoc JSON for ${this._packageName}...`);
+        utils.log(`GENERATE_DOCS: Generating Typedoc JSON for ${this._packageName}...`);
         const jsonFilePath = path.join(this._packagePath, 'generated_docs', 'index.json');
+        const mdFileDir = path.join(this._packagePath, 'docs');
+        const mdReferencePath = `${mdFileDir}/reference.mdx`;
         const projectFiles = typeDocExtraFileIncludes.join(' ');
         const cwd = path.join(constants.monorepoRootPath, 'packages', this._packageName);
         // HACK: For some reason calling `typedoc` command directly from here, even with `cwd` set to the
@@ -208,47 +206,28 @@ export class DocGenerateAndUploadUtils {
         await execAsync(`JSON_FILE_PATH=${jsonFilePath} PROJECT_FILES="${projectFiles}" yarn docs:json`, {
             cwd,
         });
+        utils.log(`GENERATE_DOCS: Generating Typedoc Markdown for ${this._packageName}...`);
+        await execAsync(`MD_FILE_DIR=${mdFileDir} PROJECT_FILES="${projectFiles}" yarn docs:md`, {
+            cwd,
+        });
 
-        utils.log('GENERATE_UPLOAD_DOCS: Modifying Typedoc JSON to our custom format...');
+        utils.log('GENERATE_DOCS: Modifying Markdown To Exclude Unexported Items...');
         const typedocOutputString = readFileSync(jsonFilePath).toString();
+        const markdownOutputString = readFileSync(mdReferencePath).toString();
         const typedocOutput = JSON.parse(typedocOutputString);
         const standardizedTypedocOutput = this._standardizeTypedocOutputTopLevelChildNames(typedocOutput);
-        const modifiedTypedocOutput = this._pruneTypedocOutput(standardizedTypedocOutput);
+        const { modifiedTypedocOutput, modifiedMarkdownOutput } = this._pruneTypedocOutput(
+            standardizedTypedocOutput,
+            markdownOutputString,
+        );
 
         if (!_.includes(docGenConfigs.TYPES_ONLY_LIBRARIES, this._packageName)) {
             const propertyName = ''; // Root has no property name
-            const referenceNames = DocGenerateAndUploadUtils._getAllReferenceNames(
+            const referenceNames = DocGenerateUtils._getAllReferenceNames(propertyName, modifiedTypedocOutput, []);
-                propertyName,
-                modifiedTypedocOutput,
-                [],
-            );
             this._lookForUnusedExportedTypesThrowIfExists(referenceNames, modifiedTypedocOutput);
             this._lookForMissingReferenceExportsThrowIfExists(referenceNames);
         }
 
-        // Some of our packages re-export external package exports in their index.ts
-        // Typedoc is incapable of rendering these packages, so we need to special-case them
-        const externalExportToLink: { [externalExport: string]: string } = {};
-        const externalExportsWithoutLinks: string[] = [];
-        const externalExports: string[] = this._getAllExternalExports();
-        _.each(externalExports, externalExport => {
-            const linkIfExists = docGenConfigs.EXTERNAL_EXPORT_TO_LINK[externalExport];
-            if (linkIfExists === undefined) {
-                externalExportsWithoutLinks.push(externalExport);
-                return;
-            }
-            externalExportToLink[externalExport] = linkIfExists;
-        });
-        if (!_.isEmpty(externalExportsWithoutLinks)) {
-            throw new Error(
-                `Found the following external exports in ${
-                    this._packageName
-                }'s index.ts:\n ${externalExportsWithoutLinks.join(
-                    '\n',
-                )}\nThey are missing from the EXTERNAL_EXPORT_TO_LINK mapping. Add them and try again.`,
-            );
-        }
-
         const exportPathToTypedocNames: ExportNameToTypedocNames = {};
         _.each(modifiedTypedocOutput.children, file => {
             const exportPath = this._findExportPathGivenTypedocName(file.name);
@@ -258,45 +237,12 @@ export class DocGenerateAndUploadUtils {
                     : [...exportPathToTypedocNames[exportPath], file.name];
         });
 
-        // Since we need additional metadata included in the doc JSON, we nest the TypeDoc JSON
+        utils.log(`GENERATE_DOCS: Delete Doc JSON in: ${jsonFilePath}`);
-        // within our own custom, versioned docsJson format.
+        unlinkSync(jsonFilePath);
-        const docJson = {
+        utils.log(`GENERATE_DOCS: Saving Doc MD to: ${mdReferencePath}`);
-            version: docGenConfigs.DOC_JSON_VERSION,
+        writeFileSync(mdReferencePath, modifiedMarkdownOutput);
-            metadata: {
-                exportPathToTypedocNames,
-                exportPathOrder: this._exportPathOrder,
-                externalTypeToLink: docGenConfigs.EXTERNAL_TYPE_TO_LINK,
-                externalExportToLink,
-            },
-            typedocJson: modifiedTypedocOutput,
-        };
-        utils.log(`GENERATE_UPLOAD_DOCS: Saving Doc JSON to: ${jsonFilePath}`);
-        writeFileSync(jsonFilePath, JSON.stringify(docJson, null, 2));
 
-        if (this._shouldUploadDocs) {
+        utils.log(`GENERATE_DOCS: Doc generation done for ${this._packageName}`);
-            await this._uploadDocsAsync(jsonFilePath, cwd);
-        }
-        utils.log(`GENERATE_UPLOAD_DOCS: Doc generation done for ${this._packageName}`);
-    }
-    private async _uploadDocsAsync(jsonFilePath: string, cwd: string): Promise<void> {
-        const fileName = `v${this._packageJson.version}.json`;
-        utils.log(`GENERATE_UPLOAD_DOCS: Doc generation successful, uploading docs... as ${fileName}`);
-
-        const S3BucketPath = this._isStaging
-            ? `s3://staging-doc-jsons/${this._packageName}/`
-            : `s3://doc-jsons/${this._packageName}/`;
-        const s3Url = `${S3BucketPath}${fileName}`;
-        await execAsync(
-            `aws s3 cp ${jsonFilePath} ${s3Url} --profile 0xproject --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json`,
-            {
-                cwd,
-            },
-        );
-        utils.log(`GENERATE_UPLOAD_DOCS: Docs uploaded to S3 bucket: ${S3BucketPath}`);
-        // Remove the generated docs directory
-        await execAsync(`rm -rf ${jsonFilePath}`, {
-            cwd,
-        });
     }
     /**
      *  Look for types that are used by the public interface but are missing from a package's index.ts
@@ -324,7 +270,7 @@ export class DocGenerateAndUploadUtils {
      * Look for exported types that are not used by the package's public interface
      */
     private _lookForUnusedExportedTypesThrowIfExists(referenceNames: string[], typedocOutput: any): void {
-        const exportedTypes = DocGenerateAndUploadUtils._getAllTypeNames(typedocOutput, []);
+        const exportedTypes = DocGenerateUtils._getAllTypeNames(typedocOutput, []);
         const excessiveReferences = _.difference(exportedTypes, referenceNames);
         const excessiveReferencesExceptIgnored = _.difference(
             excessiveReferences,
@@ -344,36 +290,51 @@ export class DocGenerateAndUploadUtils {
      * - the constructor is to be ignored
      * - it begins with an underscore (i.e is private)
      */
-    private _pruneTypedocOutput(typedocOutput: any): any {
+    private _pruneTypedocOutput(typedocOutput: any, markdownOutput: string): any {
         const modifiedTypedocOutput = _.cloneDeep(typedocOutput);
+        let modifiedMarkdownOutput = markdownOutput;
         _.each(typedocOutput.children, (file, i) => {
             const exportPath = this._findExportPathGivenTypedocName(file.name);
             const exportItems = this._exportPathToExportedItems[exportPath];
             _.each(file.children, (child, j) => {
                 const isNotExported = !_.includes(exportItems, child.name);
                 if (isNotExported) {
+                    const item = typedocOutput.children[i].children[j];
+                    let regexp;
+                    switch (item.kindString) {
+                        case 'Interface':
+                            regexp = new RegExp(`# Interface: ${item.name}[\\s\\S]*?(<hr \\/>)`, 'g');
+                            modifiedMarkdownOutput = modifiedMarkdownOutput.replace(regexp, '$1');
+                            break;
+
+                        case 'Enumeration':
+                            regexp = new RegExp(`# Enumeration: ${item.name}[\\s\\S]*?(<hr \\/>)`, 'g');
+                            modifiedMarkdownOutput = modifiedMarkdownOutput.replace(regexp, '$1');
+                            break;
+
+                        case 'Class':
+                            regexp = new RegExp(`# Class: ${item.name}[\\s\\S]*?(<hr \\/>)`, 'g');
+                            modifiedMarkdownOutput = modifiedMarkdownOutput.replace(regexp, '$1');
+                            break;
+
+                        case 'Type alias':
+                            regexp = new RegExp(`#  ${item.name}[\\s\\S]*?(___)`, 'g');
+                            modifiedMarkdownOutput = modifiedMarkdownOutput.replace(regexp, '$1');
+                            break;
+
+                        default:
+                        // Noop
+                    }
                     delete modifiedTypedocOutput.children[i].children[j];
                     return;
                 }
-
-                const innerChildren = typedocOutput.children[i].children[j].children;
-                _.each(innerChildren, (innerChild, k) => {
-                    const isHiddenConstructor =
-                        child.kindString === 'Class' &&
-                        _.includes(docGenConfigs.CLASSES_WITH_HIDDEN_CONSTRUCTORS, child.name) &&
-                        innerChild.kindString === 'Constructor';
-                    const isPrivate = _.startsWith(innerChild.name, '_');
-                    if (isHiddenConstructor || isPrivate) {
-                        delete modifiedTypedocOutput.children[i].children[j].children[k];
-                    }
-                });
-                modifiedTypedocOutput.children[i].children[j].children = _.compact(
-                    modifiedTypedocOutput.children[i].children[j].children,
-                );
             });
             modifiedTypedocOutput.children[i].children = _.compact(modifiedTypedocOutput.children[i].children);
         });
-        return modifiedTypedocOutput;
+        return {
+            modifiedTypedocOutput,
+            modifiedMarkdownOutput,
+        };
     }
     /**
      * Unfortunately TypeDoc children names will only be prefixed with the name of the package _if_ we passed
@@ -459,7 +420,7 @@ export class DocGenerateAndUploadUtils {
 
             const typeDocSourceIncludes = new Set();
             const pathToIndex = `${pathIfExists}/src/index.ts`;
-            const exportInfo = DocGenerateAndUploadUtils._getExportPathToExportedItems(pathToIndex);
+            const exportInfo = DocGenerateUtils._getExportPathToExportedItems(pathToIndex);
             const innerExportPathToExportedItems = exportInfo.exportPathToExportedItems;
             _.each(exportedItems, exportName => {
                 _.each(innerExportPathToExportedItems, (innerExportItems, innerExportPath) => {
@@ -468,7 +429,7 @@ export class DocGenerateAndUploadUtils {
                     }
                     if (!_.startsWith(innerExportPath, './')) {
                         throw new Error(
-                            `GENERATE_UPLOAD_DOCS: WARNING - ${
+                            `GENERATE_DOCS: WARNING - ${
                                 this._packageName
                             } is exporting one of ${innerExportItems} which is
                             itself exported from an external package. To fix this, export the external dependency directly,

packages/order-utils/package.json

@@ -21,7 +21,7 @@
         "fix": "tslint --fix --format stylish --project .",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/sol-compiler/package.json

@@ -24,7 +24,7 @@
         "test:circleci": "yarn test:coverage",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/sol-coverage/package.json

@@ -15,7 +15,7 @@
         "clean": "shx rm -rf lib src/artifacts generated_docs",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/sol-profiler/package.json

@@ -15,7 +15,7 @@
         "clean": "shx rm -rf lib src/artifacts generated_docs",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/sol-trace/package.json

@@ -15,7 +15,7 @@
         "clean": "shx rm -rf lib src/artifacts generated_docs",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/subproviders/package.json

@@ -24,7 +24,7 @@
         "test:integration": "run-s clean build run_mocha_integration",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {

packages/web3-wrapper/package.json

@@ -22,7 +22,7 @@
         "coverage:report:lcov": "nyc report --reporter=text-lcov > coverage/lcov.info",
         "diff_docs": "git diff --exit-code ./docs",
         "s3:sync_md_docs": "aws s3 sync ./docs s3://docs-markdown/${npm_package_name}/v${npm_package_version} --profile 0xproject --region us-east-1 --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers",
-        "docs:md": "ts-doc-gen --sourceDir=./src --output=./docs --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
+        "docs:md": "ts-doc-gen --sourceDir='$PROJECT_FILES' --output=$MD_FILE_DIR --fileExtension=mdx --tsconfig=./typedoc-tsconfig.json",
         "docs:json": "typedoc --excludePrivate --excludeExternals --ignoreCompilerErrors --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
     },
     "config": {