From b04d07815f47018655b70b4152090b566f568af1 Mon Sep 17 00:00:00 2001 From: Brandon Millman Date: Mon, 27 Nov 2017 12:10:26 -0800 Subject: Add md directory to website package and change generated docs directory --- .gitignore | 2 +- packages/0x.js/package.json | 2 +- packages/0x.js/scripts/postpublish.js | 3 ++- packages/connect/package.json | 2 +- packages/connect/scripts/postpublish.js | 3 ++- packages/website/md/docs/0xjs/async.md | 23 ++++++++++++++++ packages/website/md/docs/0xjs/errors.md | 1 + packages/website/md/docs/0xjs/installation.md | 31 ++++++++++++++++++++++ packages/website/md/docs/0xjs/introduction.md | 1 + packages/website/md/docs/0xjs/versioning.md | 1 + packages/website/md/docs/connect/installation.md | 15 +++++++++++ packages/website/md/docs/connect/introduction.md | 1 + .../md/docs/smart_contracts/introduction.md | 8 ++++++ scripts/postpublish_utils.js | 2 ++ 14 files changed, 90 insertions(+), 5 deletions(-) create mode 100644 packages/website/md/docs/0xjs/async.md create mode 100644 packages/website/md/docs/0xjs/errors.md create mode 100644 packages/website/md/docs/0xjs/installation.md create mode 100644 packages/website/md/docs/0xjs/introduction.md create mode 100644 packages/website/md/docs/0xjs/versioning.md create mode 100644 packages/website/md/docs/connect/installation.md create mode 100644 packages/website/md/docs/connect/introduction.md create mode 100644 packages/website/md/docs/smart_contracts/introduction.md diff --git a/.gitignore b/.gitignore index 68773f3c2..11fbb8499 100644 --- a/.gitignore +++ b/.gitignore @@ -63,7 +63,7 @@ lib/ _bundles # generated documentation -docs/ +generated_docs/ TODO.md diff --git a/packages/0x.js/package.json b/packages/0x.js/package.json index afca00fe9..d60d7dabb 100644 --- a/packages/0x.js/package.json +++ b/packages/0x.js/package.json @@ -15,7 +15,7 @@ "prebuild": "npm run clean", "build": "run-p build:umd:prod build:commonjs; exit 0;", "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --json $JSON_FILE_PATH $PROJECT_DIR", - "upload_docs_json": "aws s3 cp docs/index.json $S3_URL --profile 0xproject --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type aplication/json", + "upload_docs_json": "aws s3 cp generated_docs/index.json $S3_URL --profile 0xproject --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json", "lint": "tslint src/**/*.ts test/**/*.ts", "test:circleci": "run-s test:coverage report_test_coverage && if [ $CIRCLE_BRANCH = \"development\" ]; then yarn test:umd; fi", "test": "run-s clean test:commonjs", diff --git a/packages/0x.js/scripts/postpublish.js b/packages/0x.js/scripts/postpublish.js index ffc68afb4..28484a8bd 100644 --- a/packages/0x.js/scripts/postpublish.js +++ b/packages/0x.js/scripts/postpublish.js @@ -21,8 +21,9 @@ postpublish_utils.getLatestTagAndVersionAsync(subPackageName) }) .then(function(release) { console.log('POSTPUBLISH: Release successful, generating docs...'); + const jsonFilePath = __dirname + '/../' + postpublish_utils.generatedDocsDirectoryName + '/index.json'; return execAsync( - 'JSON_FILE_PATH=' + __dirname + '/../docs/index.json PROJECT_DIR=' + __dirname + '/.. yarn docs:json', + 'JSON_FILE_PATH=' + jsonFilePath + ' PROJECT_DIR=' + __dirname + '/.. yarn docs:json', { cwd, } diff --git a/packages/connect/package.json b/packages/connect/package.json index 9131eef14..00378397c 100644 --- a/packages/connect/package.json +++ b/packages/connect/package.json @@ -15,7 +15,7 @@ "build": "tsc", "clean": "shx rm -rf _bundles lib test_temp", "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --json $JSON_FILE_PATH $PROJECT_DIR", - "upload_docs_json": "aws s3 cp docs/index.json $S3_URL --profile 0xproject --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type aplication/json", + "upload_docs_json": "aws s3 cp generated_docs/index.json $S3_URL --profile 0xproject --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json", "copy_test_fixtures": "copyfiles -u 2 './test/fixtures/**/*.json' ./lib/test/fixtures", "lint": "tslint src/**/*.ts test/**/*.ts", "run_mocha": "mocha lib/test/**/*_test.js", diff --git a/packages/connect/scripts/postpublish.js b/packages/connect/scripts/postpublish.js index ba0f8507d..e6a2cc065 100644 --- a/packages/connect/scripts/postpublish.js +++ b/packages/connect/scripts/postpublish.js @@ -17,8 +17,9 @@ postpublish_utils.getLatestTagAndVersionAsync(subPackageName) }) .then(function(release) { console.log('POSTPUBLISH: Release successful, generating docs...'); + const jsonFilePath = __dirname + '/../' + postpublish_utils.generatedDocsDirectoryName + '/index.json'; return execAsync( - 'JSON_FILE_PATH=' + __dirname + '/../docs/index.json PROJECT_DIR=' + __dirname + '/.. yarn docs:json', + 'JSON_FILE_PATH=' + jsonFilePath + ' PROJECT_DIR=' + __dirname + '/.. yarn docs:json', { cwd, } diff --git a/packages/website/md/docs/0xjs/async.md b/packages/website/md/docs/0xjs/async.md new file mode 100644 index 000000000..63924c76c --- /dev/null +++ b/packages/website/md/docs/0xjs/async.md @@ -0,0 +1,23 @@ +0x.js is a promise-based library. This means that whenever an asynchronous call is required, the library method will return a native Javascript promise. You can therefore choose between using `promise` or `async/await` syntax when calling our async methods. + +*Async/await syntax (recommended):* +```javascript +try { + var availableAddresses = await zeroEx.getAvailableAddressesAsync(); +} catch (error) { + console.log('Caught error: ', error); +} +``` + +*Promise syntax:* +```javascript +zeroEx.getAvailableAddressesAsync() + .then(function(availableAddresses) { + console.log(availableAddresses); + }) + .catch(function(error) { + console.log('Caught error: ', error); + }); +``` + +As is the convention with promise-based libraries, if an error occurs, it is thrown. It is the callers responsibility to catch thrown errors and to handle them appropriately. diff --git a/packages/website/md/docs/0xjs/errors.md b/packages/website/md/docs/0xjs/errors.md new file mode 100644 index 000000000..e97973ccf --- /dev/null +++ b/packages/website/md/docs/0xjs/errors.md @@ -0,0 +1 @@ +All error messages thrown by the 0x.js library are part of a documented string enum. Each error message is in all-caps, snake-case format. This makes the error messages easily identifiable, unique and grep-able. The error enums listing all possible errors the library could throw can be found in the `Types` section. diff --git a/packages/website/md/docs/0xjs/installation.md b/packages/website/md/docs/0xjs/installation.md new file mode 100644 index 000000000..457b27a04 --- /dev/null +++ b/packages/website/md/docs/0xjs/installation.md @@ -0,0 +1,31 @@ +0x.js ships as both a [UMD](https://github.com/umdjs/umd) module and a [CommonJS](https://en.wikipedia.org/wiki/CommonJS) package. + +#### CommonJS *(recommended)*: + +**Install** + +```bash +npm install 0x.js --save +``` + +**Import** + +```javascript +import {ZeroEx} from '0x.js'; +``` + +#### UMD: + +**Install** + +Download the UMD module from our [releases page](https://github.com/0xProject/0x.js/releases) and add it to your project. + +**Import** + +```html + +``` + +### Wiki + +Check out our [wiki](https://0xproject.com/wiki) for articles on how to get 0x.js setup with TestRPC, Infura and more! diff --git a/packages/website/md/docs/0xjs/introduction.md b/packages/website/md/docs/0xjs/introduction.md new file mode 100644 index 000000000..7bad3eaa9 --- /dev/null +++ b/packages/website/md/docs/0xjs/introduction.md @@ -0,0 +1 @@ +Welcome to the [0x.js](https://github.com/0xProject/0x.js) documentation! 0x.js is a Javascript library for interacting with the 0x protocol. With it, you can easily make calls to the 0x smart contracts as well as any ERC20 token. Functionality includes generating, signing, filling and cancelling orders, verifying an orders signature, setting or checking a users ERC20 token balance/allowance and much more. diff --git a/packages/website/md/docs/0xjs/versioning.md b/packages/website/md/docs/0xjs/versioning.md new file mode 100644 index 000000000..6bcaa5b4d --- /dev/null +++ b/packages/website/md/docs/0xjs/versioning.md @@ -0,0 +1 @@ +This project adheres to the [Semantic Versioning 2.0.0](http://semver.org/) specification. The library's public interface includes all the methods, properties and types included in the documentation. Since the library is still an alpha, it's public interface is not yet stable and we will introduce backward incompatible changes to the interface without incrementing the major version until the `1.0.0` release. Our convention until then will be to increment the minor version whenever we introduce backward incompatible changes to the public interface, and to increment the patch version otherwise. This way, it is safe for you to include 0x.js in your projects with the tilda (e.g `~0.22.0`) without fear that a patch update would break your app. diff --git a/packages/website/md/docs/connect/installation.md b/packages/website/md/docs/connect/installation.md new file mode 100644 index 000000000..2d3755352 --- /dev/null +++ b/packages/website/md/docs/connect/installation.md @@ -0,0 +1,15 @@ +**Install** + +```bash +npm install @0xproject/connect --save +``` + +**Import** + +```javascript +import {HttpRelayerClient} from '@0xproject/connect'; +``` + +### Wiki + +Check out our [@0xproject/connect introduction tutorial](https://0xproject.com/wiki#Intro-Tutorial:Connect) for articles on how to get 0x.js setup with TestRPC, Infura and more! diff --git a/packages/website/md/docs/connect/introduction.md b/packages/website/md/docs/connect/introduction.md new file mode 100644 index 000000000..9b49cafff --- /dev/null +++ b/packages/website/md/docs/connect/introduction.md @@ -0,0 +1 @@ +Welcome to the [@0xproject/connect](https://github.com/0xProject/0x.js/tree/development/packages/connect) documentation! @0xproject/connect is a Javascript library that makes it easy to interact with Relayers that conform to the [Standard Relayer API](https://github.com/0xProject/standard-relayer-api). Functionality includes getting supported token pairs from a relayer, getting orders filtered by different attributes, getting individual orders specified by order hash, getting orderbooks for specific token pairs, getting fee information, and submitting orders. diff --git a/packages/website/md/docs/smart_contracts/introduction.md b/packages/website/md/docs/smart_contracts/introduction.md new file mode 100644 index 000000000..406177f84 --- /dev/null +++ b/packages/website/md/docs/smart_contracts/introduction.md @@ -0,0 +1,8 @@ +Welcome to the [0x smart contracts](https://github.com/0xProject/contracts) documentation! This documentation is intended for dApp developers who want to integrate 0x exchange functionality directly into their own smart contracts. + +### Helpful wiki articles: + +- [Overview of 0x protocol architecture](https://0xproject.com/wiki#Architecture) +- [0x smart contract interactions](https://0xproject.com/wiki#Contract-Interactions) +- [Deployed smart contract addresses](https://0xproject.com/wiki#Deployed-Addresses) +- [0x protocol message format](https://0xproject.com/wiki#Message-Format) diff --git a/scripts/postpublish_utils.js b/scripts/postpublish_utils.js index 4f9798e60..e2c23ee14 100644 --- a/scripts/postpublish_utils.js +++ b/scripts/postpublish_utils.js @@ -5,6 +5,7 @@ const publishRelease = require('publish-release'); const publishReleaseAsync = promisify(publishRelease); const githubPersonalAccessToken = process.env.GITHUB_PERSONAL_ACCESS_TOKEN_0X_JS; +const generatedDocsDirectoryName = 'generated_docs'; module.exports = { getLatestTagAndVersionAsync: function(subPackageName) { @@ -48,4 +49,5 @@ module.exports = { const releaseName = subPackageName + ' v' + version; return releaseName; }, + generatedDocsDirectoryName, }; -- cgit v1.2.3