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

Merge pull request #519 from 0xProject/fix/docImprovements

Browse Source 
Doc fixes and improvements
This commit is contained in:
Fabio Berger
2018-04-12 08:56:33 +09:00
committed by GitHub
parent c47fb8f9a8 faedd2fa0b
commit 5eb90697c8
24 changed files with 121 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -32,7 +32,7 @@ This repository is a monorepo including the 0x protocol smart contracts and nume
| [`@0xproject/react-docs`](/packages/react-docs) | [![npm](https://img.shields.io/npm/v/@0xproject/react-docs.svg)](https://www.npmjs.com/package/@0xproject/react-docs) | React documentation component for rendering TypeDoc & Doxity generated JSON |
| [`@0xproject/react-shared`](/packages/react-shared) | [![npm](https://img.shields.io/npm/v/@0xproject/react-shared.svg)](https://www.npmjs.com/package/@0xproject/react-shared) | 0x shared react components |
| [`@0xproject/sra-report`](/packages/sra-report) | [![npm](https://img.shields.io/npm/v/@0xproject/sra-report.svg)](https://www.npmjs.com/package/@0xproject/sra-report) | Generate reports for standard relayer API compliance |
| [`@0xproject/sol-cov`](/packages/sol-cov) | [![npm](https://img.shields.io/npm/v/@0xproject/sol-cov.svg)](https://www.npmjs.com/package/@0xproject/sol-cov) | Solidity test coverage tool tool |
| [`@0xproject/sol-cov`](/packages/sol-cov) | [![npm](https://img.shields.io/npm/v/@0xproject/sol-cov.svg)](https://www.npmjs.com/package/@0xproject/sol-cov) | Solidity test coverage tool |
| [`@0xproject/subproviders`](/packages/subproviders) | [![npm](https://img.shields.io/npm/v/@0xproject/subproviders.svg)](https://www.npmjs.com/package/@0xproject/subproviders) | Useful web3 subproviders (e.g LedgerSubprovider) |
| [`@0xproject/tslint-config`](/packages/tslint-config) | [![npm](https://img.shields.io/npm/v/@0xproject/tslint-config.svg)](https://www.npmjs.com/package/@0xproject/tslint-config) | Custom 0x development TSLint rules |
| [`@0xproject/types`](/packages/types) | [![npm](https://img.shields.io/npm/v/@0xproject/types.svg)](https://www.npmjs.com/package/@0xproject/types) | Shared type declarations |

2
packages/0x.js/CHANGELOG.json
View File

@@ -14,7 +14,7 @@
"changes": [
{
"note":
"Removed `ZeroExError.TransactionMiningTimeout` and moved it to '@0xproject/web3_wrapper' `Web3WrapperErrors.TransactionMiningTimeout`",
"Removed `ZeroExError.TransactionMiningTimeout` and moved it to '@0xproject/web3-wrapper' `Web3WrapperErrors.TransactionMiningTimeout`",
"pr": 485
}
],

2
packages/0x.js/README.md
View File

@@ -2,7 +2,7 @@
A TypeScript/Javascript library for interacting with the 0x protocol.
### Read the [Documentation](https://0xproject.com/docs/0xjs).
### Read the [Documentation](https://0xproject.com/docs/0x.js).
## Installation

2
packages/dev-utils/CHANGELOG.json
View File

@@ -33,7 +33,7 @@
"note": "Reduce npm package size by adding an `.npmignore` file."
},
{
"note": "Move `@0xproject/web3_wrapper` to dependencies from devDependencies."
"note": "Move `@0xproject/web3-wrapper` to dependencies from devDependencies."
}
],
"timestamp": 1521298800

2
packages/dev-utils/CHANGELOG.md
View File

@@ -20,7 +20,7 @@ CHANGELOG
## v0.3.1 - _March 17, 2018_
* Reduce npm package size by adding an `.npmignore` file.
* Move `@0xproject/web3_wrapper` to dependencies from devDependencies.
* Move `@0xproject/web3-wrapper` to dependencies from devDependencies.
## v0.3.0 - _March 17, 2018_

13
packages/react-docs/CHANGELOG.json
View File

@@ -1,4 +1,17 @@
[
{
"version": "0.0.8",
"changes": [
{
"note": "Added support for rendering default param values",
"pr": 519
},
{
"note": "Added support for rendering nested function types within interface types",
"pr": 519
}
]
},
{
"timestamp": 1523462196,
"version": "0.0.7",

2
packages/react-docs/src/components/documentation.tsx
View File

@@ -337,7 +337,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta
return (
<div key={`property-${property.name}-${property.type.name}`} className="pb3">
<code className={`hljs ${constants.TYPE_TO_SYNTAX[this.props.docsInfo.type]}`}>
{property.name}:
{property.name}:{' '}
<Type type={property.type} sectionName={sectionName} docsInfo={this.props.docsInfo} />
</code>
{property.source && (

3
packages/react-docs/src/components/interface.tsx
View File

@@ -19,7 +19,7 @@ export function Interface(props: InterfaceProps) {
return (
<span key={`property-${property.name}-${property.type}-${type.name}`}>
{property.name}:{' '}
{property.type.typeDocType !== TypeDocTypes.Reflection ? (
{property.type && property.type.typeDocType !== TypeDocTypes.Reflection ? (
<Type type={property.type} sectionName={props.sectionName} docsInfo={props.docsInfo} />
) : (
<Signature
@@ -27,7 +27,6 @@ export function Interface(props: InterfaceProps) {
returnType={property.type.method.returnType}
parameters={property.type.method.parameters}
typeParameter={property.type.method.typeParameter}
callPath={property.type.method.callPath}
sectionName={props.sectionName}
shouldHideMethodName={true}
shouldUseArrowSyntax={true}

2
packages/react-docs/src/components/signature.tsx
View File

@@ -91,6 +91,7 @@ function renderParameters(
) {
const params = _.map(parameters, (p: Parameter) => {
const isOptional = p.isOptional;
const hasDefaultValue = !_.isUndefined(p.defaultValue);
const type = (
<Type
type={p.type}
@@ -103,6 +104,7 @@ function renderParameters(
<span key={`param-${p.type}-${p.name}`}>
{p.name}
{isOptional && '?'}: {type}
{hasDefaultValue && ` = ${p.defaultValue}`}
</span>
);
});

1
packages/react-docs/src/components/type.tsx
View File

@@ -109,7 +109,6 @@ export function Type(props: TypeProps): any {
returnType={type.method.returnType}
parameters={type.method.parameters}
typeParameter={type.method.typeParameter}
callPath={type.method.callPath}
sectionName={props.sectionName}
shouldHideMethodName={true}
shouldUseArrowSyntax={true}

1
packages/react-docs/src/types.ts
View File

@@ -140,6 +140,7 @@ export interface Parameter {
comment: string;
isOptional: boolean;
type: Type;
defaultValue?: string;
}
export interface TypeParameter {

11
packages/react-docs/src/utils/typedoc_utils.ts
View File

@@ -14,6 +14,7 @@ import {
Type,
TypeDocNode,
TypeDocType,
TypeDocTypes,
TypeParameter,
TypescriptFunction,
TypescriptMethod,
@@ -221,9 +222,16 @@ export const typeDocUtils = {
const childrenIfExist = !_.isUndefined(entity.children)
? _.map(entity.children, (child: TypeDocNode) => {
const childTypeIfExists = !_.isUndefined(child.type)
let childTypeIfExists = !_.isUndefined(child.type)
? typeDocUtils._convertType(child.type, sections, sectionName, docId)
: undefined;
if (child.kindString === KindString.Method) {
childTypeIfExists = {
name: child.name,
typeDocType: TypeDocTypes.Reflection,
method: this._convertMethod(child, isConstructor, sections, sectionName, docId),
};
}
const c: CustomTypeChild = {
name: child.name,
type: childTypeIfExists,
@@ -387,6 +395,7 @@ export const typeDocUtils = {
name: entity.name,
comment,
isOptional,
defaultValue: entity.defaultValue,
type,
};
return parameter;

3
packages/sol-cov/package.json
View File

@@ -24,7 +24,8 @@
"assets": [],
"docPublishConfigs": {
"extraFileIncludes": [
"../subproviders/src/types.ts"
"../subproviders/src/types.ts",
"../types/src/index.ts"
],
"s3BucketPath": "s3://doc-jsons/sol-cov/",
"s3StagingBucketPath": "s3://staging-doc-jsons/sol-cov/"

8
packages/types/src/index.ts
View File

@@ -1,7 +1,13 @@
import { BigNumber } from 'bignumber.js';
export type JSONRPCErrorCallback = (err: Error | null, result?: JSONRPCResponsePayload) => void;
/**
* Do not create your own provider. Use an existing provider from a Web3 or ProviderEngine library
* Read more about Providers in the 0x wiki.
*/
export interface Provider {
sendAsync(payload: JSONRPCRequestPayload, callback: (err: Error, result: JSONRPCResponsePayload) => void): void;
sendAsync(payload: JSONRPCRequestPayload, callback: JSONRPCErrorCallback): void;
}
export type ContractAbi = AbiDefinition[];

2
packages/web3-wrapper/README.md
View File

@@ -2,7 +2,7 @@
Wrapped version of web3 with a nicer interface that is used across 0x projects and packages.
### Read the [Documentation](https://0xproject.com/docs/web3_wrapper).
### Read the [Documentation](https://0xproject.com/docs/web3-wrapper).
## Installation

12
packages/website/ts/components/top_bar/top_bar.tsx
View File

@@ -15,7 +15,7 @@ import { TopBarMenuItem } from 'ts/components/top_bar/top_bar_menu_item';
import { DropDown } from 'ts/components/ui/drop_down';
import { Identicon } from 'ts/components/ui/identicon';
import { Dispatcher } from 'ts/redux/dispatcher';
import { Deco, Key, ProviderType, WebsitePaths } from 'ts/types';
import { Deco, Key, ProviderType, WebsiteLegacyPaths, WebsitePaths } from 'ts/types';
import { constants } from 'ts/utils/constants';
import { Translate } from 'ts/utils/translate';
@@ -462,7 +462,10 @@ export class TopBar extends React.Component<TopBarProps, TopBarState> {
return _.includes(this.props.location.pathname, WebsitePaths.FAQ);
}
private _isViewing0xjsDocs() {
return _.includes(this.props.location.pathname, WebsitePaths.ZeroExJs);
return (
_.includes(this.props.location.pathname, WebsitePaths.ZeroExJs) ||
_.includes(this.props.location.pathname, WebsiteLegacyPaths.ZeroExJs)
);
}
private _isViewingConnectDocs() {
return _.includes(this.props.location.pathname, WebsitePaths.Connect);
@@ -471,7 +474,10 @@ export class TopBar extends React.Component<TopBarProps, TopBarState> {
return _.includes(this.props.location.pathname, WebsitePaths.SmartContracts);
}
private _isViewingWeb3WrapperDocs() {
return _.includes(this.props.location.pathname, WebsitePaths.Web3Wrapper);
return (
_.includes(this.props.location.pathname, WebsitePaths.Web3Wrapper) ||
_.includes(this.props.location.pathname, WebsiteLegacyPaths.Web3Wrapper)
);
}
private _isViewingDeployerDocs() {
return _.includes(this.props.location.pathname, WebsitePaths.Deployer);

8
packages/website/ts/containers/sol_cov_documentation.ts
View File

@@ -44,7 +44,7 @@ const docsInfoConfig: DocsInfoConfig = {
},
sectionNameToModulePath: {
[docSections.coverageSubprovider]: ['"sol-cov/src/coverage_subprovider"'],
[docSections.types]: ['"subproviders/src/types"'],
[docSections.types]: ['"subproviders/src/types"', '"types/src/index"'],
},
menuSubsectionToVersionWhenIntroduced: {},
sections: docSections,
@@ -52,11 +52,9 @@ const docsInfoConfig: DocsInfoConfig = {
typeConfigs: {
// Note: This needs to be kept in sync with the types exported in index.ts. Unfortunately there is
// currently no way to extract the re-exported types from index.ts via TypeDoc :(
publicTypes: ['NextCallback', 'OnNextCompleted', 'ErrorCallback'],
publicTypes: ['NextCallback', 'OnNextCompleted', 'ErrorCallback', 'JSONRPCRequestPayload'],
typeNameToExternalLink: {},
typeNameToPrefix: {
JSONRPCRequestPayload: 'Web3',
},
typeNameToPrefix: {},
typeNameToDocSection: {},
},
};

12
packages/website/ts/containers/subproviders_documentation.ts
View File

@@ -91,25 +91,21 @@ const docsInfoConfig: DocsInfoConfig = {
'ErrorCallback',
'ECSignature',
'JSONRPCRequestPayloadWithMethod',
'JSONRPCRequestPayload',
'JSONRPCResponsePayload',
'AccountFetchingConfigs',
'LedgerEthereumClientFactoryAsync',
'PartialTxParams',
'LedgerEthereumClient',
'LedgerSubproviderConfigs',
'OnNextCompleted',
'Provider',
],
typeNameToExternalLink: {
Web3: 'https://github.com/ethereum/wiki/wiki/JavaScript-API',
BigNumber: 'https://github.com/0xProject/web3-typescript-typings/blob/f5bcb96/index.d.ts#L127',
JSONRPCRequestPayload: 'https://github.com/0xProject/web3-typescript-typings/blob/f5bcb96/index.d.ts#L137',
JSONRPCResponsePayload: 'https://github.com/0xProject/web3-typescript-typings/blob/f5bcb96/index.d.ts#L144',
Provider: 'https://github.com/0xProject/web3-typescript-typings/blob/f5bcb96/index.d.ts#L150',
},
typeNameToPrefix: {
JSONRPCRequestPayload: 'Web3',
JSONRPCResponsePayload: 'Web3',
Provider: 'Web3',
},
typeNameToPrefix: {},
},
};
const docsInfo = new DocsInfo(docsInfoConfig);

29
packages/website/ts/containers/web3_wrapper_documentation.ts
View File

@@ -59,15 +59,36 @@ const docsInfoConfig: DocsInfoConfig = {
'BlockWithoutTransactionData',
'CallData',
'LogEntryEvent',
'Provider',
'AbiDefinition',
'LogTopic',
'JSONRPCRequestPayload',
'JSONRPCResponsePayload',
'BlockParamLiteral',
'FunctionAbi',
'EventAbi',
'JSONRPCErrorCallback',
'MethodAbi',
'ConstructorAbi',
'FallbackAbi',
'EventParameter',
'DataItem',
'StateMutability',
'Function',
'Fallback',
'Constructor',
'Event',
'ConstructorStateMutability',
'TransactionReceiptWithDecodedLogs',
'DecodedLogArgs',
'LogWithDecodedArgs',
'ContractEventArg',
],
typeNameToExternalLink: {
Web3: 'https://github.com/ethereum/wiki/wiki/JavaScript-API',
Provider: 'https://github.com/0xProject/web3-typescript-typings/blob/f5bcb96/index.d.ts#L150',
BigNumber: 'http://mikemcl.github.io/bignumber.js',
},
typeNameToPrefix: {
Provider: 'Web3',
},
typeNameToPrefix: {},
typeNameToDocSection: {
Web3Wrapper: docSections.web3Wrapper,
},

18
packages/website/ts/containers/zero_ex_js_documentation.ts
View File

@@ -168,21 +168,15 @@ const docsInfoConfig: DocsInfoConfig = {
'OrderStateWatcherConfig',
'FilterObject',
'OrderRelevantState',
'JSONRPCRequestPayload',
'JSONRPCResponsePayload',
'JSONRPCErrorCallback',
'LogEntryEvent',
'LogEntry',
],
typeNameToPrefix: {
Provider: 'Web3',
DecodedLogEntryEvent: 'Web3',
LogEntryEvent: 'Web3',
CallData: 'Web3',
LogEntry: 'Web3',
},
typeNameToPrefix: {},
typeNameToExternalLink: {
Web3: constants.URL_WEB3_DOCS,
Provider: constants.URL_WEB3_PROVIDER_DOCS,
BigNumber: constants.URL_BIGNUMBERJS_GITHUB,
DecodedLogEntryEvent: constants.URL_WEB3_DECODED_LOG_ENTRY_EVENT,
LogEntryEvent: constants.URL_WEB3_LOG_ENTRY_EVENT,
LogEntry: 'https://github.com/0xProject/web3-typescript-typings/blob/f5bcb96/index.d.ts#L366',
},
typeNameToDocSection: {
ExchangeWrapper: 'exchange',

13
packages/website/ts/index.tsx
View File

@@ -15,7 +15,7 @@ import { createLazyComponent } from 'ts/lazy_component';
import { trackedTokenStorage } from 'ts/local_storage/tracked_token_storage';
import { tradeHistoryStorage } from 'ts/local_storage/trade_history_storage';
import { reducer, State } from 'ts/redux/reducer';
import { WebsitePaths } from 'ts/types';
import { WebsiteLegacyPaths, WebsitePaths } from 'ts/types';
import { analytics } from 'ts/utils/analytics';
import { muiTheme } from 'ts/utils/mui_theme';
import { utils } from 'ts/utils/utils';
@@ -98,6 +98,17 @@ render(
path={`${WebsitePaths.SmartContracts}/:version?`}
component={LazySmartContractsDocumentation}
/>
{/* Legacy endpoints */}
<Route
path={`${WebsiteLegacyPaths.ZeroExJs}/:version?`}
component={LazyZeroExJSDocumentation}
/>
<Route
path={`${WebsiteLegacyPaths.Web3Wrapper}/:version?`}
component={LazyWeb3WrapperDocumentation}
/>
<Route component={NotFound as any} />
</Switch>
</div>

8
packages/website/ts/pages/documentation/doc_page.tsx
View File

@@ -8,14 +8,14 @@ import semverSort = require('semver-sort');
import { SidebarHeader } from 'ts/components/sidebar_header';
import { TopBar } from 'ts/components/top_bar/top_bar';
import { Dispatcher } from 'ts/redux/dispatcher';
import { DocPackages, Environments } from 'ts/types';
import { DocPackages } from 'ts/types';
import { configs } from 'ts/utils/configs';
import { constants } from 'ts/utils/constants';
import { docUtils } from 'ts/utils/doc_utils';
import { Translate } from 'ts/utils/translate';
import { utils } from 'ts/utils/utils';
const isDevelopment = configs.ENVIRONMENT === Environments.DEVELOPMENT;
const isDevelopmentOrStaging = utils.isDevelopment() || utils.isStaging();
const DEFAULT_ICON = 'docs.png';
const ZERO_EX_JS_VERSION_MISSING_TOPLEVEL_PATH = '0.32.4';
@@ -106,7 +106,9 @@ export class DocPage extends React.Component<DocPageProps, DocPageState> {
}
private async _fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists?: string): Promise<void> {
const folderName = docIdToSubpackageName[this.props.docsInfo.id];
const docBucketRoot = isDevelopment ? constants.S3_STAGING_DOC_BUCKET_ROOT : constants.S3_DOC_BUCKET_ROOT;
const docBucketRoot = isDevelopmentOrStaging
? constants.S3_STAGING_DOC_BUCKET_ROOT
: constants.S3_DOC_BUCKET_ROOT;
const versionToFilePath = await docUtils.getVersionToFilePathAsync(docBucketRoot, folderName);
const versions = _.keys(versionToFilePath);
this.props.dispatcher.updateAvailableDocVersions(versions);

9
packages/website/ts/types.ts
View File

@@ -341,17 +341,22 @@ export enum Docs {
SmartContracts,
}
export enum WebsiteLegacyPaths {
ZeroExJs = '/docs/0xjs',
Web3Wrapper = '/docs/web3_wrapper',
}
export enum WebsitePaths {
Portal = '/portal',
Wiki = '/wiki',
ZeroExJs = '/docs/0xjs',
ZeroExJs = '/docs/0x.js',
Home = '/',
FAQ = '/faq',
About = '/about',
Whitepaper = '/pdfs/0x_white_paper.pdf',
SmartContracts = '/docs/contracts',
Connect = '/docs/connect',
Web3Wrapper = '/docs/web3_wrapper',
Web3Wrapper = '/docs/web3-wrapper',
Deployer = '/docs/deployer',
JSONSchemas = '/docs/json-schemas',
SolCov = '/docs/sol-cov',

8
packages/website/ts/utils/utils.ts
View File

@@ -5,7 +5,7 @@ import { BigNumber } from '@0xproject/utils';
import deepEqual = require('deep-equal');
import * as _ from 'lodash';
import * as moment from 'moment';
import { Order, Providers, ScreenWidths, Side, SideToAssetToken, Token, TokenByAddress } from 'ts/types';
import { Environments, Order, Providers, ScreenWidths, Side, SideToAssetToken, Token, TokenByAddress } from 'ts/types';
import { configs } from 'ts/utils/configs';
import { constants } from 'ts/utils/constants';
import * as u2f from 'ts/vendor/u2f_api';
@@ -292,4 +292,10 @@ export const utils = {
}
return parsedProviderName;
},
isDevelopment() {
return configs.ENVIRONMENT === Environments.DEVELOPMENT;
},
isStaging() {
return _.includes(window.location.href, configs.DOMAIN_STAGING);
},
};