crowetic/protocol
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
fabioberger
2019-08-28 18:09:29 +02:00
parent 7efcf9066c
commit 53864d3817
22 changed files with 111 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
package.json
View File

@@ -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_md_docs": "wsrun docs:md --exclude-missing",
"generate_doc": "node ./packages/monorepo-scripts/lib/doc_generate.js",
"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;",

6
packages/0x.js/package.json
View File

@@ -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",

2
packages/asset-buyer/package.json
View File

@@ -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": {

2
packages/asset-swapper/package.json
View File

@@ -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": {

2
packages/connect/package.json
View File

@@ -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": {

2
packages/ethereum-types/package.json
View File

@@ -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": {

2
packages/json-schemas/package.json
View File

@@ -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": {

2
packages/migrations/package.json
View File

@@ -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 .",

2
packages/monorepo-scripts/package.json
View File

@@ -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": {

24
packages/monorepo-scripts/src/doc_gen_configs.ts
View File

@@ -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

24
packages/monorepo-scripts/src/doc_generate.ts Normal file
View File

@@ -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);
});

37
packages/monorepo-scripts/src/doc_generate_and_upload.ts
View File

@@ -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);
});

41
packages/monorepo-scripts/src/publish.ts
View File

@@ -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(
packagesWithDocs: Package[],
isStaging: boolean,
shouldUploadDocs: boolean,
): Promise<void> {
async function generateDocMDAsync(packagesWithDocs: Package[]): 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 });

2
packages/monorepo-scripts/src/types.ts
View File

@@ -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[];
}

163
packages/monorepo-scripts/src/utils/doc_generate_and_upload_utils.ts → packages/monorepo-scripts/src/utils/doc_generate_utils.ts
View File

@@ -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 {
private readonly _isStaging: boolean;
private readonly _shouldUploadDocs: boolean;
export class DocGenerateUtils {
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) {
this._isStaging = isStaging;
constructor(packageName: string) {
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(
propertyName,
modifiedTypedocOutput,
[],
);
const referenceNames = DocGenerateUtils._getAllReferenceNames(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
// within our own custom, versioned docsJson format.
const docJson = {
version: docGenConfigs.DOC_JSON_VERSION,
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));
utils.log(`GENERATE_DOCS: Delete Doc JSON in: ${jsonFilePath}`);
unlinkSync(jsonFilePath);
utils.log(`GENERATE_DOCS: Saving Doc MD to: ${mdReferencePath}`);
writeFileSync(mdReferencePath, modifiedMarkdownOutput);
if (this._shouldUploadDocs) {
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,
});
utils.log(`GENERATE_DOCS: Doc generation done for ${this._packageName}`);
}
/**
* 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,

2
packages/order-utils/package.json
View File

@@ -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": {

2
packages/sol-compiler/package.json
View File

@@ -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": {

2
packages/sol-coverage/package.json
View File

@@ -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": {

2
packages/sol-profiler/package.json
View File

@@ -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": {

2
packages/sol-trace/package.json
View File

@@ -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": {

2
packages/subproviders/package.json
View File

@@ -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": {

2
packages/web3-wrapper/package.json
View File

@@ -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": {