Merge pull request #1301 from 0xProject/feature/migrationsDocRef

Add Migrations Doc Ref

package.json

@@ -40,7 +40,7 @@
     },
     "config": {
         "mnemonic": "concert load couple harbor equip island argue ramp clarify fence smart topic",
-        "packagesWithDocPages": "0x.js connect json-schemas subproviders web3-wrapper contract-wrappers order-utils order-watcher sol-compiler sol-cov ethereum-types asset-buyer"
+        "packagesWithDocPages": "0x.js connect json-schemas subproviders web3-wrapper contract-wrappers order-utils order-watcher sol-compiler sol-cov ethereum-types asset-buyer migrations"
     },
     "bundlewatch": {
         "files": [

packages/migrations/CHANGELOG.json

@@ -1,4 +1,14 @@
 [
+    {
+        "version": "2.1.0",
+        "changes": [
+            {
+                "note":
+                    "Export all type declarations used by the public interface, as well as the `ContractAddresses` mapping",
+                "pr": 1301
+            }
+        ]
+    },
     {
         "timestamp": 1542208198,
         "version": "2.0.4",

packages/migrations/package.json

@@ -13,7 +13,13 @@
         "clean": "shx rm -rf lib",
         "lint": "tslint --format stylish --project .",
         "migrate:v2": "run-s build script:migrate:v2",
-        "script:migrate:v2": "node ./lib/migrate.js --contracts-version 2.0.0"
+        "script:migrate:v2": "node ./lib/migrate.js",
+        "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES"
+    },
+    "config": {
+        "postpublish": {
+            "assets": []
+        }
     },
     "license": "Apache-2.0",
     "devDependencies": {
@@ -25,6 +31,7 @@
         "npm-run-all": "^4.1.2",
         "shx": "^0.2.2",
         "tslint": "5.11.0",
+        "typedoc": "0.13.0",
         "typescript": "3.0.1",
         "yargs": "^10.0.3"
     },

packages/migrations/src/index.ts

@@ -1 +1,11 @@
+export {
+    Provider,
+    TxData,
+    JSONRPCRequestPayload,
+    JSONRPCErrorCallback,
+    TxDataPayable,
+    JSONRPCResponsePayload,
+    JSONRPCResponseError,
+} from 'ethereum-types';
+export { ContractAddresses } from '@0x/contract-addresses';
 export { runMigrationsAsync, runMigrationsOnceAsync } from './migration';

packages/migrations/src/migration.ts

@@ -11,10 +11,9 @@ import { erc20TokenInfo, erc721TokenInfo } from './utils/token_info';
 
 /**
  * Creates and deploys all the contracts that are required for the latest
- * version of the 0x protocol. Custom migrations can be defined here. This will
- * be called with the CLI 'migrate:v2' command.
- * @param provider  Web3 provider instance.
- * @param txDefaults Default transaction values to use when deploying contracts.
+ * version of the 0x protocol.
+ * @param provider  Web3 provider instance. Your provider instance should connect to the testnet you want to deploy to.
+ * @param txDefaults Default transaction values to use when deploying contracts (e.g., specify the desired contract creator with the `from` parameter).
  * @returns The addresses of the contracts that were deployed.
  */
 export async function runMigrationsAsync(provider: Provider, txDefaults: Partial<TxData>): Promise<ContractAddresses> {
@@ -159,8 +158,8 @@ let _cachedContractAddresses: ContractAddresses;
  * Exactly like runMigrationsAsync but will only run the migrations the first
  * time it is called. Any subsequent calls will return the cached contract
  * addresses.
- * @param provider  Web3 provider instance.
- * @param txDefaults Default transaction values to use when deploying contracts.
+ * @param provider  Web3 provider instance. Your provider instance should connect to the testnet you want to deploy to.
+ * @param txDefaults Default transaction values to use when deploying contracts (e.g., specify the desired contract creator with the `from` parameter).
  * @returns The addresses of the contracts that were deployed.
  */
 export async function runMigrationsOnceAsync(

packages/migrations/typedoc-tsconfig.json

@@ -0,0 +1,7 @@
+{
+    "extends": "../../typedoc-tsconfig",
+    "compilerOptions": {
+        "outDir": "lib"
+    },
+    "include": ["./src/**/*", "./test/**/*"]
+}

packages/website/md/docs/migrations/1/installation.md

@@ -0,0 +1,17 @@
+**Install**
+
+```bash
+yarn add @0x/migrations
+```
+
+**Import**
+
+```javascript
+import { runMigrationsAsync } from '@0x/migrations';
+```
+
+or
+
+```javascript
+var runMigrationsAsync = require('@0x/migrations').runMigrationsAsync;
+```

packages/website/md/docs/migrations/1/introduction.md

@@ -0,0 +1 @@
+Welcome to the [@0x/migrations](https://github.com/0xProject/0x-monorepo/tree/development/packages/migrations) documentation! This package is intended for developers who would like to deploy the 0x protocol system of smart contracts to a custom testnet. If you want to test against existing testnets, check out our pre-deployed [Ganache snapshot](https://0xproject.com/wiki#Ganache-Setup-Guide) or where 0x is already deployed on [popular testnets](https://0xproject.com/wiki#Deployed-Addresses).

packages/website/ts/containers/migrations_documentation.ts

@@ -0,0 +1,66 @@
+import { DocsInfo, DocsInfoConfig, SupportedDocJson } from '@0x/react-docs';
+import * as React from 'react';
+import { connect } from 'react-redux';
+import { Dispatch } from 'redux';
+import { DocPage as DocPageComponent, DocPageProps } from 'ts/pages/documentation/doc_page';
+import { Dispatcher } from 'ts/redux/dispatcher';
+import { State } from 'ts/redux/reducer';
+import { DocPackages, ScreenWidths } from 'ts/types';
+import { Translate } from 'ts/utils/translate';
+
+/* tslint:disable:no-var-requires */
+const IntroMarkdown1 = require('md/docs/migrations/1/introduction');
+const InstallationMarkdown1 = require('md/docs/migrations/1/installation');
+/* tslint:enable:no-var-requires */
+
+const markdownSections = {
+    introduction: 'introduction',
+    installation: 'installation',
+};
+
+const docsInfoConfig: DocsInfoConfig = {
+    id: DocPackages.Migrations,
+    packageName: '@0x/migrations',
+    type: SupportedDocJson.TypeDoc,
+    displayName: 'Migrations',
+    packageUrl: 'https://github.com/0xProject/0x-monorepo',
+    markdownMenu: {
+        'getting-started': [markdownSections.introduction, markdownSections.installation],
+    },
+    sectionNameToMarkdownByVersion: {
+        '2.0.4': {
+            [markdownSections.introduction]: IntroMarkdown1,
+            [markdownSections.installation]: InstallationMarkdown1,
+        },
+    },
+    markdownSections,
+};
+const docsInfo = new DocsInfo(docsInfoConfig);
+
+interface ConnectedState {
+    docsVersion: string;
+    availableDocVersions: string[];
+    docsInfo: DocsInfo;
+    translate: Translate;
+    screenWidth: ScreenWidths;
+}
+
+interface ConnectedDispatch {
+    dispatcher: Dispatcher;
+}
+
+const mapStateToProps = (state: State, _ownProps: DocPageProps): ConnectedState => ({
+    docsVersion: state.docsVersion,
+    availableDocVersions: state.availableDocVersions,
+    translate: state.translate,
+    docsInfo,
+    screenWidth: state.screenWidth,
+});
+
+const mapDispatchToProps = (dispatch: Dispatch<State>): ConnectedDispatch => ({
+    dispatcher: new Dispatcher(dispatch),
+});
+
+export const Documentation: React.ComponentClass<DocPageProps> = connect(mapStateToProps, mapDispatchToProps)(
+    DocPageComponent,
+);

packages/website/ts/index.tsx

@@ -40,6 +40,9 @@ const LazyZeroExJSDocumentation = createLazyComponent('Documentation', async ()
 const LazyContractWrappersDocumentation = createLazyComponent('Documentation', async () =>
     import(/* webpackChunkName: "contractWrapperDocs" */ 'ts/containers/contract_wrappers_documentation'),
 );
+const LazyMigrationsDocumentation = createLazyComponent('Documentation', async () =>
+    import(/* webpackChunkName: "migrationsDocs" */ 'ts/containers/migrations_documentation'),
+);
 const LazyOrderWatcherDocumentation = createLazyComponent('Documentation', async () =>
     import(/* webpackChunkName: "orderWatcherDocs" */ 'ts/containers/order_watcher_documentation'),
 );
@@ -102,6 +105,10 @@ render(
                                     path={`${WebsitePaths.ContractWrappers}/:version?`}
                                     component={LazyContractWrappersDocumentation}
                                 />
+                                <Route
+                                    path={`${WebsitePaths.Migrations}/:version?`}
+                                    component={LazyMigrationsDocumentation}
+                                />
                                 <Route
                                     path={`${WebsitePaths.OrderWatcher}/:version?`}
                                     component={LazyOrderWatcherDocumentation}

packages/website/ts/pages/documentation/doc_page.tsx

@@ -39,6 +39,7 @@ const docIdToSubpackageName: { [id: string]: string } = {
     [DocPackages.OrderWatcher]: 'order-watcher',
     [DocPackages.EthereumTypes]: 'ethereum-types',
     [DocPackages.AssetBuyer]: 'asset-buyer',
+    [DocPackages.Migrations]: 'migrations',
 };
 
 export interface DocPageProps {

packages/website/ts/pages/documentation/docs_home.tsx

@@ -107,6 +107,14 @@ const CATEGORY_TO_PACKAGES: ObjectMap<Package[]> = {
                 to: WebsitePaths.ContractWrappers,
             },
         },
+        {
+            description:
+                "A package to deploy the 0x protocol's system of smart contracts to the testnet of your choice",
+            link: {
+                title: '@0x/migrations',
+                to: WebsitePaths.Migrations,
+            },
+        },
         {
             description:
                 'A collection of 0x-related JSON-schemas (incl. SRA request/response schemas, 0x order message format schema, etc...)',
@@ -131,6 +139,23 @@ const CATEGORY_TO_PACKAGES: ObjectMap<Package[]> = {
                 to: WebsitePaths.OrderWatcher,
             },
         },
+        {
+            description:
+                'A tiny utility library for getting known deployed contract addresses for a particular network.',
+            link: {
+                title: '@0x/contract-addresses',
+                to: 'https://www.npmjs.com/package/@0x/contract-addresses',
+                shouldOpenInNewTab: true,
+            },
+        },
+        {
+            description: 'Smart contract compilation artifacts for the latest version of the 0x protocol.',
+            link: {
+                title: '@0x/contract-artifacts',
+                to: 'https://www.npmjs.com/package/@0x/contract-artifacts',
+                shouldOpenInNewTab: true,
+            },
+        },
         {
             description:
                 'Contains the Standard Relayer API OpenAPI Spec. The package distributes both a javascript object version and a json version.',

packages/website/ts/types.ts

@@ -366,6 +366,7 @@ export enum WebsitePaths {
     OrderUtils = '/docs/order-utils',
     EthereumTypes = '/docs/ethereum-types',
     AssetBuyer = '/docs/asset-buyer',
+    Migrations = '/docs/migrations',
     Careers = '/careers',
 }
 
@@ -383,6 +384,7 @@ export enum DocPackages {
     ContractWrappers = 'CONTRACT_WRAPPERS',
     OrderWatcher = 'ORDER_WATCHER',
     AssetBuyer = 'ASSET_BUYER',
+    Migrations = 'MIGRATIONS',
 }
 
 export enum Key {