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

Merge development into 3.0 (#2170)

Browse Source 
* Added longer timeout for algolia admin operations. Added an option to apply hidden and custom labels to filters from algolia. Added sorting guides (alphabetically) and tools (by community maintenance and alphabetically).

* Fixed some types in guides

* Updated webpack, webpack-dev-server, webpack-bundle-analyzer, webpack-cli versions

* Updated / cleaned up babel and mdx packages

* Updated terser webpack plugin; Removed uglify plugin (unused). Added parallel option for terser. Added target browsers and cache directory option for babel-loader

* Webpack changes: using eval-source-map for development, added parallel option to Terser plugin, added cache loader and caching directory to mdx / babel loaders.

* Removed unusued pkg: body-scroll-lock

* Removed unused jsonschema / @types/jsonschema packages

* Removed unused less node package, adjusted less loader rules to match other loaders in webpack config

* Removed unusued node-sass package. Left sass-loader for webpack intact.

* Removed unused package react-lazyload

* Removed unused package react-typist

* Removed react-tap-event types as it's not used anymore. Reinstalled node-sass as a dev dependency as it's needed by sass-loader

* Moves @0x/types and @0x/typescript-typings to devDependencies

* Replaced react loadable (only used in Icon) with the native react lazy / suspense. Removed loadable nad its types from package.json

* Removed unused make-promises-safe package

* Moved animations to public and compressed files

* Added opening step links in new tab if the url is valid

* Moved @0x/types back to dependencies.

* Added animation wrapper with positioning props. Updated animations for core concepts.

* Replaced images for core concepts. Fixed a bug causing duplicate props on image and its container in mdx

* Remove legacy FAQ

* Update yarn.lock

* Add MD docs diff test to CI

* Remove unused dep

* Update docs to latest format

* Update yarn.lock

* Update ts-doc-gen with fix for multi-link lines

* Final docs gen

* Fix home route

* Update yarn.lock

* Add Golang Mesh RPC package and update versions

* Update the tools MDX files from authoritative S3 before build and dev server start

* Gitignore the tool MDX files in website repo

* Redirect old docs pages and wiki to new doc pages

* Move out Algolia indexing command-line tool out of website and remove need to expose admin key

* Add updating tools from S3 and indexing content on Algolia to deployment commands

* Add note about admin API env var needed for indexing docs

* Remove scripts gitignore since we don't have monorepo scripts in each package anymore

* Segregate indexes by environment

* Fixed 404 display for docs pages

* Removed webpack bundle analyzer

* Fix search and indexing

* Use `yarn` because otherwise the flags don't get passed down properly

* Improve indexing comment

* Remove legacy doc pages

* Fix linter errors

* Fix clean command to remove bundles recursively

* Revert react and react-dom versions in Instant

* Remove old doc md files

* Fix links

* Fix prettier

* Combine @0x/utils exports

* Update doc links

* Remove unused components

* Fix TS error

* Add missing new line

* Update Guides

* Ignore auto-generated MDX in website repo

* Prettier fix

* Add all guides to the sitemap.txt

* Add MMing guide

* Fix Get Started links

* Add 0x Extensions guide

* Replace all links to wiki with links to guides section

* Fix all /docs/{pkg} links to /docs/tools/{pkg}

* Remove deployer endpoint that is no longer used

* Fix links in Core Concepts

* Fixed regex to not remove hashes on links beyond the initial one

* Fixed huge width on instant screenshot

* Cleaned up core concept illustrations

* Started updating tool titles

* Fixed sectionizing headings in docs: Nested sections do not get wrapped in parent sections anymore; only sectionizing headings that need to be sectionized (i.e. that appear in the table of contents)

* Stylstic fix for the new way we sectionize headings / table of contents

* Change CoordinatorWrapper constructor to take a provider

* Added autolinking headings in mdx docs

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

* Update ts-doc-gen

* Pass in provider, not Web3Wrapper

* Add back logic to prune out private methods

* Write algolia_metadata to utils dir

* Remove duplicate algolia_meta

* Add more packages to those we generate docs for and remove unused flags

* Update reference.mdx files

* Hide tools from homepage that have isHidden flag

* Link 0x.js to it's reference page

* Update tool naming to be more human readable

* Remove order-watcher reference doc

* Add blurb about on-chain API Explorer

* Add "On-chain" prefix to section name

* Remove committed reference file

* Sorting guides by difficulty and alphabetically

* Pushed sorting guides titles case-insensitive

* Sorting tools by difficulty and alphabetically. Removed icons from featured tools. Extracted common difficultyOrder constant

* Update ts-doc-gen so that it properly converts module relative links to anchor links

* Update doc references

* Remove "Relayers" topic/tag

* Prettier fix

* Remove hr so we don't have a bunch in a row

* Cleaned up CLI tag and added link to tools on API page

* Cleaned up some Guide titles

* Added bug bounty program guide

* Fixed a bug in algolia_meta

* Thrid level of nesting / temporary webpack config

* Open help link in new tab

* Link Python tools to doc pages not PyPi

* Fix links in guides

* Remove unused variables

* Revert webpack config

* Extracted common styles for levels of nesting deeper than 1 in the mdx table of contents

* Smoother animation on active table of contents state change

* Autolink headings in mdx only up to h3. Added heading sizes (in px) for h4,h5,h6 in mdx headings

* Fix prettier

* Adjusted font-size for paragraph, ordered and unordered lists. Fixed line-heights and colors too.

* Update ts-doc-gen and the reference docs

* Replace 0xproject.com urls with 0x.org

* Update README links

* Fix header sizes to display optimally in sidebar

* Fixed an issue with other nodes than text being parsed incorrectly in the table of contents

* Fixed styles for table of contents

* Use a different babel plugin that works in a production webpack build

* Unbroke build process / generating toc

* Changed line-height to 1.6 for paragraph

* Adjust scrollbar / toc height to available space

* Fixed some types

* Remove unnecessary link

* Fix casing on TypeScript

* Fix casing of PyPI

* Remove doc gen from abi-gen-wrappers since it'll be tested via contract-wrappers

* Fix MD docs and make sure generated contract wrappers are being rendered

* Remove generated docs in clean

* Correctly copying code samples

* Several additional fixes to the reference MDX docs

* Changed tools to Tools & Libraries - top nav left as just tools

* Changed references from Asset Buyer to Asset Swapper

* Changed trader keyword to trading

* Nevermind, changed back to Trader

* Sneaking in updated product dropdown menu titles based on Will's feedback

* Removed the word wiki from resources dropdown

* Open legal guide in same window

* Removed the isCommunity filter / custom filter labels functionality (only used for that before)

* Update ts-doc-gen version to one that fixes issues with Object Literals and removes Hierarchy sections and Module headers

* update yarn.lock

* Remove unused code

* Remove unused import

* Remove unused imports

* Remove unused import

* Fix prettier

* Update outdating dep version

* Created a color scheme for code snippets. Fixed language not being passed to some code blocks in two guides.

* Update abi-gen-wrappers dep version

* Update Algolia to production account

* Fix prettier

* Fix prettier in algolia_meta

* Remove packages/dev-tools-pages folder and update yarn.lock

* Remove other random references to dev-tools-pages

* Fix website

* Changed the order of indices in search suggestions

* Removed a comment

* Added scrollbar size adjustment on resize / scroll

* Rendering sidebar on mobile without any event listeners / taxing calculations / changes in height

* Added a performance comment

* Simplified table of contents

* Update ganache-cli to later version

* Remove bundle dirs too

* Added keeping active link in view when scrolling content in the docs

* Increase available memory for webpack

* Update contract addresses

* Update market-making guide to mention Mesh as an alternative to SRA

* Update Web3 Provider Explained guide

* Re-wrote Ganache Setup guide into a Setting up a local 0x testnet guide

* Export more of abi-gen-wrappers from contract-wrappers

* Final update of reference docs

* Add contract-wrappers MD docs and update it's index.ts so that no types are missing

* Fix prettier

* Increase the memory allocation for building the website

* Remove use of remove type

* Check if link is a valid url in mdx inline link: if so, open in a new tab, if not, same tab.

* Print out which snapshot version is being downloaded

* Updated CHANGELOGS & MD docs

* Publish

 - @0x/contracts-asset-proxy@2.2.7
 - @0x/contracts-coordinator@2.0.12
 - @0x/contracts-dev-utils@0.0.9
 - @0x/contracts-erc1155@1.1.14
 - @0x/contracts-erc20@2.2.13
 - @0x/contracts-erc721@2.1.14
 - @0x/contracts-exchange-forwarder@3.0.11
 - @0x/contracts-exchange-libs@3.0.7
 - @0x/contracts-exchange@2.1.13
 - @0x/contracts-extensions@4.0.7
 - @0x/contracts-multisig@3.1.13
 - @0x/contracts-test-utils@3.1.15
 - @0x/contracts-utils@3.2.3
 - 0x.js@7.0.1
 - @0x/abi-gen-wrappers@5.3.1
 - @0x/abi-gen@4.2.0
 - @0x/assert@2.1.5
 - @0x/asset-buyer@6.1.13
 - @0x/asset-swapper@1.0.3
 - @0x/base-contract@5.3.3
 - @0x/connect@5.0.18
 - @0x/contract-artifacts@2.2.1
 - @0x/contract-wrappers@12.0.0
 - @0x/contracts-gen@1.0.14
 - @0x/dev-tools-pages@0.0.30
 - @0x/dev-utils@2.3.2
 - ethereum-types@2.1.5
 - @0x/fill-scenarios@3.0.18
 - @0x/instant@1.0.30
 - @0x/json-schemas@4.0.1
 - @0x/migrations@4.3.1
 - @0x/monorepo-scripts@1.0.36
 - @0x/order-utils@8.3.1
 - @0x/sol-compiler@3.1.14
 - @0x/sol-coverage@3.0.11
 - @0x/sol-doc@2.0.18
 - @0x/sol-profiler@3.1.13
 - @0x/sol-resolver@2.0.10
 - @0x/sol-trace@2.0.19
 - @0x/sol-tracing-utils@6.0.18
 - @0x/sra-spec@2.0.16
 - @0x/subproviders@5.0.3
 - @0x/testnet-faucets@1.0.86
 - @0x/types@2.4.2
 - @0x/typescript-typings@4.2.5
 - @0x/utils@4.5.1
 - @0x/web3-wrapper@6.0.12
 - @0x/website@0.0.89

* Remove the website from the monorepo

* Update yarn.lock

* Remove website files that were accidentally merged back in

* Use local EVM for pure functions (#2108)

* add local evm for pure functions

* increase container size to >=8gb for static-tests

* increase max bundle size because of ethereumjs-vm dependency

* add declarations for ethereumjs-vm in @0x/typescript-typings

* Make `OrdersChannelSubscriptionOpts` conform to SRAv2

* Make it easier to use validateOrderFillableOrThrowAsync (#2096)

* make it easier to use validateOrderFillableOrThrowAsync

* add unit tests, use DevUtils

* remove dependency on @0x/order-utils from @0x/migrations

* add devUtils to contract-wrappers (#2146)

* Delete docs in S3 bucket before uploading latest version so we only ever have one version uploaded at a time

* Update to new ts-doc-gen version that fixes links in "Inherited from" lines

* try to fix instant build

* Remove redoc-cli as a dep from sra-spec

* Smooth out some last incompatible types

* Fix prettier

* Add terser-webpack-plugin to 0x.js deps

* @0x/orderbook

* AssetSwapper to use @0x/orderbook

* Remove unused imported type

* Prevent double websocket connections

* Fix build error

* fixed consumer inconsistency bug

* linted + added convenience functionality

* minor changes/typo fixes

* updated websocket

* updated for prettier

* Fix versions and exported types

* move log tests to @0x/abi-gen; delete exchange_wrapper_test (#2160)

* Remove unused exported types

* Fix exports from asset-swapper

* Update exported types for docs

* Update mesh client dep

* Move perPage and 18 precision lower to re-use

* fix ABI encoding/decoding functions (#2165)

* Fix typo at contract import (#2102)

* Updated CHANGELOGS & MD docs

* Publish

 - @0x/contracts-asset-proxy@2.2.8
 - @0x/contracts-coordinator@2.0.13
 - @0x/contracts-dev-utils@0.0.10
 - @0x/contracts-erc1155@1.1.15
 - @0x/contracts-erc20@2.2.14
 - @0x/contracts-erc721@2.1.15
 - @0x/contracts-exchange-forwarder@3.0.12
 - @0x/contracts-exchange-libs@3.0.8
 - @0x/contracts-exchange@2.1.14
 - @0x/contracts-extensions@4.0.8
 - @0x/contracts-multisig@3.1.14
 - @0x/contracts-test-utils@3.1.16
 - @0x/contracts-utils@3.2.4
 - 0x.js@7.0.2
 - @0x/abi-gen-wrappers@5.3.2
 - @0x/abi-gen@4.2.1
 - @0x/assert@2.1.6
 - @0x/asset-buyer@6.1.14
 - @0x/asset-swapper@2.0.0
 - @0x/base-contract@5.4.0
 - @0x/connect@5.0.19
 - @0x/contract-addresses@3.2.0
 - @0x/contract-artifacts@2.2.2
 - @0x/contract-wrappers@12.1.0
 - @0x/contracts-gen@1.0.15
 - @0x/dev-utils@2.3.3
 - ethereum-types@2.1.6
 - @0x/fill-scenarios@3.0.19
 - @0x/instant@1.0.31
 - @0x/json-schemas@4.0.2
 - @0x/migrations@4.3.2
 - @0x/monorepo-scripts@1.0.37
 - @0x/order-utils@8.4.0
 - @0x/orderbook@0.0.2
 - @0x/sol-compiler@3.1.15
 - @0x/sol-coverage@3.0.12
 - @0x/sol-doc@2.0.19
 - @0x/sol-profiler@3.1.14
 - @0x/sol-resolver@2.0.11
 - @0x/sol-trace@2.0.20
 - @0x/sol-tracing-utils@6.0.19
 - @0x/sra-spec@2.0.17
 - @0x/subproviders@5.0.4
 - @0x/testnet-faucets@1.0.87
 - @0x/types@2.4.3
 - @0x/typescript-typings@4.3.0
 - @0x/utils@4.5.2
 - @0x/web3-wrapper@6.0.13

* fix circleci diff

* update changelog
This commit is contained in:
Xianny
2019-09-19 19:43:08 -07:00
committed by GitHub
parent 2253f214a6
commit a57dd427ca
1281 changed files with 81209 additions and 56841 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -5,54 +5,27 @@ export const docGenConfigs: DocGenConfigs = {
DOC_JSON_VERSION: '0.0.1',
// Some types that are exposed by our package's public interface are external types. As such, we won't
// be able to render their definitions. Instead we link to them using this lookup.
EXTERNAL_TYPE_TO_LINK: {
Array: 'https://developer.mozilla.org/pt-PT/docs/Web/JavaScript/Reference/Global_Objects/Array',
BigNumber: 'http://mikemcl.github.io/bignumber.js',
Error: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error',
ErrorConstructor: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error',
Buffer: 'https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/v9/index.d.ts#L262',
'solc.StandardContractOutput':
'https://solidity.readthedocs.io/en/v0.4.24/using-the-compiler.html#output-description',
'solc.CompilerSettings': 'https://solidity.readthedocs.io/en/v0.4.24/using-the-compiler.html#input-description',
Schema:
'https://github.com/tdegrunt/jsonschema/blob/5c2edd4baba149964aec0f23c87ad12c25a50dfb/lib/index.d.ts#L49',
Uint8Array: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array',
EXTERNAL_TYPE_MAP: {
Array: true,
BigNumber: true,
Error: true,
ErrorConstructor: true,
Buffer: true,
'solc.StandardContractOutput': true,
'solc.CompilerSettings': true,
Schema: true,
Uint8Array: true,
// HACK: CI can handle these without the namespace but some local setups (Jacob) require the namespace prefix
// This is duplicated until we can discover the source of the issue.
GanacheOpts: 'https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/ganache-core/index.d.ts#L8',
keystore: 'https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/eth-lightwallet/index.d.ts#L36',
'Ganache.GanacheOpts':
'https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/ganache-core/index.d.ts#L8',
'lightwallet.keystore':
'https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/eth-lightwallet/index.d.ts#L36',
GanacheOpts: true,
keystore: true,
'Ganache.GanacheOpts': true,
PromiseWithTransactionHash: true,
// HACK: Asset-swapper specifies marketSell and marketBuy quotes with a descriminant MarketOperation Type to ignore the error, linking Buy and Sell to MarketOperation
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',
Buy: true,
Sell: true,
IterableIterator: true,
},
// 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);
});

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

@@ -7,7 +7,6 @@ import * as promisify from 'es6-promisify';
import * as fs from 'fs';
import * as _ from 'lodash';
import * as moment from 'moment';
import opn = require('opn');
import * as path from 'path';
import { exec as execAsync, spawn as spawnAsync } from 'promisify-child-process';
import * as prompt from 'prompt';
@@ -19,11 +18,10 @@ 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';
const NPM_NAMESPACE = '@0x/';
const TODAYS_TIMESTAMP = moment().unix();
async function confirmAsync(message: string): Promise<void> {
@@ -50,7 +48,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
@@ -71,9 +68,12 @@ async function confirmAsync(message: string): Promise<void> {
}
});
// Push changelog changes to Github
// Generate markdown docs for packages
await generateDocMDAsync(packagesWithDocs);
// Push changelogs changes and markdown docs to Github
if (!configs.IS_LOCAL_PUBLISH) {
await pushChangelogsToGithubAsync();
await pushChangelogsAndMDDocsToGithubAsync();
}
// Call LernaPublish
@@ -89,10 +89,10 @@ 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 });
}
const releaseNotes = await publishReleaseNotesAsync(updatedPublicPackages, isDryRun);
utils.log('Published release notes');
@@ -160,46 +160,19 @@ 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/${nameWithoutPrefix}`;
// tslint:disable-next-line:no-floating-promises
opn(link);
});
await confirmAsync('Do all the doc pages render? (y/n)');
}
async function pushChangelogsToGithubAsync(): Promise<void> {
async function pushChangelogsAndMDDocsToGithubAsync(): Promise<void> {
await execAsync(`git add . --all`, { cwd: constants.monorepoRootPath });
await execAsync(`git commit -m "Updated CHANGELOGS"`, { cwd: constants.monorepoRootPath });
await execAsync(`git commit -m "Updated CHANGELOGS & MD docs"`, { cwd: constants.monorepoRootPath });
await execAsync(`git push`, { cwd: constants.monorepoRootPath });
utils.log(`Pushed CHANGELOG updates to Github`);
utils.log(`Pushed CHANGELOG updates & updated MD docs to Github`);
}
async function updateChangeLogsAsync(updatedPublicPackages: Package[]): Promise<PackageToNextVersion> {

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

@@ -105,7 +105,7 @@ async function testInstallPackageAsync(
utils.log(`Testing ${packageName}@${lastChangelogVersion}`);
const packageDirName = path.join(...`${packageName}-test`.split('/'));
// NOTE(fabio): The `testDirectory` needs to be somewhere **outside** the monorepo root directory.
// Otherwise, it will have access to the hoisted `node_modules` directory and the Typescript missing
// Otherwise, it will have access to the hoisted `node_modules` directory and the TypeScript missing
// type errors will not be caught.
const testDirectory = path.join(monorepoRootPath, '..', '.installation-test', packageDirName);
await rimrafAsync(testDirectory);

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

@@ -43,9 +43,7 @@ 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[];
EXTERNAL_TYPE_MAP: { [externalType: string]: boolean };
IGNORED_EXCESSIVE_TYPES: string[];
TYPES_ONLY_LIBRARIES: string[];
}

173
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,14 +11,11 @@ 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;
private readonly _exportPathToExportedItems: ExportPathToExportedItems;
private readonly _exportPathOrder: string[];
private readonly _monoRepoPkgNameToPath: { [name: string]: string };
private readonly _packageJson: PackageJSON;
/**
@@ -36,10 +33,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 +68,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 +158,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,9 +176,8 @@ 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;
}
public async generateAndUploadDocsAsync(): Promise<void> {
// For each dep that is another one of our monorepo packages, we fetch it's index.ts
@@ -198,8 +192,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 +204,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 +235,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
@@ -307,7 +251,7 @@ export class DocGenerateAndUploadUtils {
_.each(referenceNames, referenceName => {
if (
!_.includes(allExportedItems, referenceName) &&
docGenConfigs.EXTERNAL_TYPE_TO_LINK[referenceName] === undefined
docGenConfigs.EXTERNAL_TYPE_MAP[referenceName] === undefined
) {
missingReferences.push(referenceName);
}
@@ -316,7 +260,7 @@ export class DocGenerateAndUploadUtils {
throw new Error(
`${this._packageName} package needs to export: \n${missingReferences.join(
'\n',
)} \nFrom it\'s index.ts. If any are from external dependencies, then add them to the EXTERNAL_TYPE_TO_LINK mapping.`,
)} \nFrom it\'s index.ts. If any are from external dependencies, then add them to the EXTERNAL_TYPE_MAP.`,
);
}
}
@@ -324,7 +268,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,26 +288,49 @@ 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, '');
break;
case 'Enumeration':
regexp = new RegExp(`(.*)# Enumeration: ${item.name}[\\s\\S]*?<hr \\/>`, 'g');
modifiedMarkdownOutput = modifiedMarkdownOutput.replace(regexp, '');
break;
case 'Class':
regexp = new RegExp(`(.*)# Class: ${item.name}[\\s\\S]*?<hr \\/>`, 'g');
modifiedMarkdownOutput = modifiedMarkdownOutput.replace(regexp, '');
break;
case 'Type alias':
regexp = new RegExp(`(.*)# ${item.name}[\\s\\S]*?(___|<hr \\/>)`, 'g');
modifiedMarkdownOutput = modifiedMarkdownOutput.replace(regexp, '');
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) {
if (isPrivate) {
delete modifiedTypedocOutput.children[i].children[j].children[k];
}
});
@@ -373,7 +340,10 @@ export class DocGenerateAndUploadUtils {
});
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
@@ -429,19 +399,6 @@ export class DocGenerateAndUploadUtils {
const matchingExportPath = sanitizedExportPathToExportPath[matchingSanitizedExportPathIfExists];
return matchingExportPath;
}
private _getAllExternalExports(): string[] {
const externalExports: string[] = [];
_.each(this._exportPathToExportedItems, (exportedItems, exportPath) => {
const pathIfExists = this._monoRepoPkgNameToPath[exportPath];
if (pathIfExists === undefined && !_.startsWith(exportPath, './')) {
_.each(exportedItems, exportedItem => {
externalExports.push(exportedItem);
});
return; // It's an external package
}
});
return externalExports;
}
private _getTypeDocFileIncludesForPackage(): string[] {
let typeDocExtraFileIncludes: string[] = [];
_.each(this._exportPathToExportedItems, (exportedItems, exportPath) => {
@@ -459,7 +416,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 +425,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,