aboutsummaryrefslogtreecommitdiffstats
path: root/packages/website/ts/pages/documentation
diff options
context:
space:
mode:
authorFabio Berger <me@fabioberger.com>2017-11-29 01:16:35 +0800
committerFabio Berger <me@fabioberger.com>2017-11-29 01:16:35 +0800
commit3472bdcfd4ea0a6145dd68972f563e483baf7e6b (patch)
tree6ed8d25cd58cd243aaf94af37f4e9d1d6a98fc85 /packages/website/ts/pages/documentation
parent78f0ab36823127b67c1ea24b7245c51ba814b16a (diff)
downloaddexon-sol-tools-3472bdcfd4ea0a6145dd68972f563e483baf7e6b.tar
dexon-sol-tools-3472bdcfd4ea0a6145dd68972f563e483baf7e6b.tar.gz
dexon-sol-tools-3472bdcfd4ea0a6145dd68972f563e483baf7e6b.tar.bz2
dexon-sol-tools-3472bdcfd4ea0a6145dd68972f563e483baf7e6b.tar.lz
dexon-sol-tools-3472bdcfd4ea0a6145dd68972f563e483baf7e6b.tar.xz
dexon-sol-tools-3472bdcfd4ea0a6145dd68972f563e483baf7e6b.tar.zst
dexon-sol-tools-3472bdcfd4ea0a6145dd68972f563e483baf7e6b.zip
Refactor docs to be more declarative, put all hard-coded doc-related data in one place so it easier to add new doc pages
Diffstat (limited to 'packages/website/ts/pages/documentation')
-rw-r--r--packages/website/ts/pages/documentation/docs_info.ts52
-rw-r--r--packages/website/ts/pages/documentation/event_definition.tsx10
-rw-r--r--packages/website/ts/pages/documentation/interface.tsx7
-rw-r--r--packages/website/ts/pages/documentation/method_block.tsx4
-rw-r--r--packages/website/ts/pages/documentation/method_signature.tsx35
-rw-r--r--packages/website/ts/pages/documentation/smart_contracts_documentation.tsx67
-rw-r--r--packages/website/ts/pages/documentation/source_link.tsx3
-rw-r--r--packages/website/ts/pages/documentation/type.tsx13
-rw-r--r--packages/website/ts/pages/documentation/type_definition.tsx8
-rw-r--r--packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx177
10 files changed, 314 insertions, 62 deletions
diff --git a/packages/website/ts/pages/documentation/docs_info.ts b/packages/website/ts/pages/documentation/docs_info.ts
new file mode 100644
index 000000000..326ebb31c
--- /dev/null
+++ b/packages/website/ts/pages/documentation/docs_info.ts
@@ -0,0 +1,52 @@
+import compareVersions = require('compare-versions');
+import * as _ from 'lodash';
+import {DocsInfoConfig, DocsMenu, SectionsMap} from 'ts/types';
+
+export class DocsInfo {
+ public packageName: string;
+ public packageUrl: string;
+ public websitePath: string;
+ public docsJsonRoot: string;
+ public menu: DocsMenu;
+ public sections: SectionsMap;
+ public sectionNameToMarkdown: {[sectionName: string]: string};
+ private docsInfo: DocsInfoConfig;
+ constructor(config: DocsInfoConfig) {
+ this.packageName = config.packageName;
+ this.packageUrl = config.packageUrl;
+ this.websitePath = config.websitePath;
+ this.docsJsonRoot = config.docsJsonRoot;
+ this.sections = config.sections;
+ this.sectionNameToMarkdown = config.sectionNameToMarkdown;
+ this.docsInfo = config;
+ }
+ public isPublicType(typeName: string): boolean {
+ if (_.isUndefined(this.docsInfo.publicTypes)) {
+ return false;
+ }
+ const isPublic = _.includes(this.docsInfo.publicTypes, typeName);
+ return isPublic;
+ }
+ public getModulePathsIfExists(sectionName: string): string[] {
+ const modulePathsIfExists = this.docsInfo.sectionNameToModulePath[sectionName];
+ return modulePathsIfExists;
+ }
+ public getMenu(selectedVersion?: string): {[section: string]: string[]} {
+ if (_.isUndefined(selectedVersion) || _.isUndefined(this.docsInfo.menuSubsectionToVersionWhenIntroduced)) {
+ return this.docsInfo.menu;
+ }
+
+ const finalMenu = _.cloneDeep(this.docsInfo.menu);
+ finalMenu.contracts = _.filter(finalMenu.contracts, (contractName: string) => {
+ const versionIntroducedIfExists = this.docsInfo.menuSubsectionToVersionWhenIntroduced[contractName];
+ if (!_.isUndefined(versionIntroducedIfExists)) {
+ const existsInSelectedVersion = compareVersions(selectedVersion,
+ versionIntroducedIfExists) >= 0;
+ return existsInSelectedVersion;
+ } else {
+ return true;
+ }
+ });
+ return finalMenu;
+ }
+}
diff --git a/packages/website/ts/pages/documentation/event_definition.tsx b/packages/website/ts/pages/documentation/event_definition.tsx
index ea75d78bc..3b1b86112 100644
--- a/packages/website/ts/pages/documentation/event_definition.tsx
+++ b/packages/website/ts/pages/documentation/event_definition.tsx
@@ -1,5 +1,6 @@
import * as _ from 'lodash';
import * as React from 'react';
+import {DocsInfo} from 'ts/pages/documentation/docs_info';
import {Type} from 'ts/pages/documentation/type';
import {AnchorTitle} from 'ts/pages/shared/anchor_title';
import {Event, EventArg, HeaderSizes} from 'ts/types';
@@ -11,6 +12,7 @@ const CUSTOM_GREEN = 'rgb(77, 162, 75)';
interface EventDefinitionProps {
event: Event;
+ docsInfo: DocsInfo;
}
interface EventDefinitionState {
@@ -53,9 +55,15 @@ export class EventDefinition extends React.Component<EventDefinitionProps, Event
private renderEventCode() {
const indexed = <span style={{color: CUSTOM_GREEN}}> indexed</span>;
const eventArgs = _.map(this.props.event.eventArgs, (eventArg: EventArg) => {
+ const t = (
+ <Type
+ type={eventArg.type}
+ docsInfo={this.props.docsInfo}
+ />
+ );
return (
<span key={`eventArg-${eventArg.name}`}>
- {eventArg.name}{eventArg.isIndexed ? indexed : ''}: <Type type={eventArg.type} />,
+ {eventArg.name}{eventArg.isIndexed ? indexed : ''}: {t},
</span>
);
});
diff --git a/packages/website/ts/pages/documentation/interface.tsx b/packages/website/ts/pages/documentation/interface.tsx
index d8d4aec32..e671db2b8 100644
--- a/packages/website/ts/pages/documentation/interface.tsx
+++ b/packages/website/ts/pages/documentation/interface.tsx
@@ -1,11 +1,13 @@
import * as _ from 'lodash';
import * as React from 'react';
+import {DocsInfo} from 'ts/pages/documentation/docs_info';
import {MethodSignature} from 'ts/pages/documentation/method_signature';
import {Type} from 'ts/pages/documentation/type';
import {CustomType, TypeDocTypes} from 'ts/types';
interface InterfaceProps {
type: CustomType;
+ docsInfo: DocsInfo;
}
export function Interface(props: InterfaceProps) {
@@ -15,11 +17,12 @@ export function Interface(props: InterfaceProps) {
<span key={`property-${property.name}-${property.type}-${type.name}`}>
{property.name}:{' '}
{property.type.typeDocType !== TypeDocTypes.Reflection ?
- <Type type={property.type} /> :
+ <Type type={property.type} docsInfo={props.docsInfo} /> :
<MethodSignature
method={property.type.method}
shouldHideMethodName={true}
shouldUseArrowSyntax={true}
+ docsInfo={props.docsInfo}
/>
},
</span>
@@ -30,7 +33,7 @@ export function Interface(props: InterfaceProps) {
const is = type.indexSignature;
const param = (
<span key={`indexSigParams-${is.keyName}-${is.keyType}-${type.name}`}>
- {is.keyName}: <Type type={is.keyType} />
+ {is.keyName}: <Type type={is.keyType} docsInfo={props.docsInfo} />
</span>
);
properties.push((
diff --git a/packages/website/ts/pages/documentation/method_block.tsx b/packages/website/ts/pages/documentation/method_block.tsx
index 026c46918..3f4eb7164 100644
--- a/packages/website/ts/pages/documentation/method_block.tsx
+++ b/packages/website/ts/pages/documentation/method_block.tsx
@@ -4,6 +4,7 @@ import {colors} from 'material-ui/styles';
import * as React from 'react';
import * as ReactMarkdown from 'react-markdown';
import {Comment} from 'ts/pages/documentation/comment';
+import {DocsInfo} from 'ts/pages/documentation/docs_info';
import {MethodSignature} from 'ts/pages/documentation/method_signature';
import {SourceLink} from 'ts/pages/documentation/source_link';
import {AnchorTitle} from 'ts/pages/shared/anchor_title';
@@ -23,6 +24,7 @@ interface MethodBlockProps {
method: SolidityMethod|TypescriptMethod;
libraryVersion: string;
typeDefinitionByName: TypeDefinitionByName;
+ docsInfo: DocsInfo;
}
interface MethodBlockState {
@@ -85,12 +87,14 @@ export class MethodBlock extends React.Component<MethodBlockProps, MethodBlockSt
<MethodSignature
method={method}
typeDefinitionByName={this.props.typeDefinitionByName}
+ docsInfo={this.props.docsInfo}
/>
</code>
{(method as TypescriptMethod).source &&
<SourceLink
version={this.props.libraryVersion}
source={(method as TypescriptMethod).source}
+ baseUrl={this.props.docsInfo.packageUrl}
/>
}
{method.comment &&
diff --git a/packages/website/ts/pages/documentation/method_signature.tsx b/packages/website/ts/pages/documentation/method_signature.tsx
index e3806b2fa..197252fb4 100644
--- a/packages/website/ts/pages/documentation/method_signature.tsx
+++ b/packages/website/ts/pages/documentation/method_signature.tsx
@@ -1,5 +1,6 @@
import * as _ from 'lodash';
import * as React from 'react';
+import {DocsInfo} from 'ts/pages/documentation/docs_info';
import {Type} from 'ts/pages/documentation/type';
import {Parameter, SolidityMethod, TypeDefinitionByName, TypescriptMethod} from 'ts/types';
@@ -8,6 +9,7 @@ interface MethodSignatureProps {
shouldHideMethodName?: boolean;
shouldUseArrowSyntax?: boolean;
typeDefinitionByName?: TypeDefinitionByName;
+ docsInfo: DocsInfo;
}
const defaultProps = {
@@ -16,45 +18,64 @@ const defaultProps = {
};
export const MethodSignature: React.SFC<MethodSignatureProps> = (props: MethodSignatureProps) => {
- const parameters = renderParameters(props.method, props.typeDefinitionByName);
+ const parameters = renderParameters(props.method, props.docsInfo, props.typeDefinitionByName);
const paramString = _.reduce(parameters, (prev: React.ReactNode, curr: React.ReactNode) => {
return [prev, ', ', curr];
});
const methodName = props.shouldHideMethodName ? '' : props.method.name;
const typeParameterIfExists = _.isUndefined((props.method as TypescriptMethod).typeParameter) ?
undefined :
- renderTypeParameter(props.method, props.typeDefinitionByName);
+ renderTypeParameter(props.method, props.docsInfo, props.typeDefinitionByName);
return (
<span>
{props.method.callPath}{methodName}{typeParameterIfExists}({paramString})
{props.shouldUseArrowSyntax ? ' => ' : ': '}
{' '}
{props.method.returnType &&
- <Type type={props.method.returnType} typeDefinitionByName={props.typeDefinitionByName}/>
+ <Type
+ type={props.method.returnType}
+ typeDefinitionByName={props.typeDefinitionByName}
+ docsInfo={props.docsInfo}
+ />
}
</span>
);
};
-function renderParameters(method: TypescriptMethod|SolidityMethod, typeDefinitionByName?: TypeDefinitionByName) {
+function renderParameters(
+ method: TypescriptMethod|SolidityMethod, docsInfo: DocsInfo, typeDefinitionByName?: TypeDefinitionByName,
+) {
const parameters = method.parameters;
const params = _.map(parameters, (p: Parameter) => {
const isOptional = p.isOptional;
+ const t = (
+ <Type
+ type={p.type}
+ typeDefinitionByName={typeDefinitionByName}
+ docsInfo={docsInfo}
+ />
+ );
return (
<span key={`param-${p.type}-${p.name}`}>
- {p.name}{isOptional && '?'}: <Type type={p.type} typeDefinitionByName={typeDefinitionByName}/>
+ {p.name}{isOptional && '?'}: {t}
</span>
);
});
return params;
}
-function renderTypeParameter(method: TypescriptMethod, typeDefinitionByName?: TypeDefinitionByName) {
+function renderTypeParameter(
+ method: TypescriptMethod, docsInfo: DocsInfo, typeDefinitionByName?: TypeDefinitionByName,
+) {
const typeParameter = method.typeParameter;
const typeParam = (
<span>
{`<${typeParameter.name} extends `}
- <Type type={typeParameter.type} typeDefinitionByName={typeDefinitionByName}/>
+ <Type
+ type={typeParameter.type}
+ typeDefinitionByName={typeDefinitionByName}
+ docsInfo={docsInfo}
+ />
{`>`}
</span>
);
diff --git a/packages/website/ts/pages/documentation/smart_contracts_documentation.tsx b/packages/website/ts/pages/documentation/smart_contracts_documentation.tsx
index 0d5751ffb..c7104e150 100644
--- a/packages/website/ts/pages/documentation/smart_contracts_documentation.tsx
+++ b/packages/website/ts/pages/documentation/smart_contracts_documentation.tsx
@@ -11,6 +11,7 @@ import semverSort = require('semver-sort');
import {TopBar} from 'ts/components/top_bar';
import {Badge} from 'ts/components/ui/badge';
import {Comment} from 'ts/pages/documentation/comment';
+import {DocsInfo} from 'ts/pages/documentation/docs_info';
import {EventDefinition} from 'ts/pages/documentation/event_definition';
import {MethodBlock} from 'ts/pages/documentation/method_block';
import {SourceLink} from 'ts/pages/documentation/source_link';
@@ -26,16 +27,17 @@ import {
CustomType,
DocAgnosticFormat,
Docs,
+ DocsInfoConfig,
DoxityDocObj,
EtherscanLinkSuffixes,
Event,
MenuSubsectionsBySection,
Networks,
Property,
- SmartContractsDocSections,
SolidityMethod,
Styles,
TypeDefinitionByName,
+ WebsitePaths,
} from 'ts/types';
import {constants} from 'ts/utils/constants';
import {docUtils} from 'ts/utils/doc_utils';
@@ -46,14 +48,36 @@ const IntroMarkdown = require('md/docs/smart_contracts/introduction');
/* tslint:enable:no-var-requires */
const SCROLL_TO_TIMEOUT = 500;
+const SCROLL_TOP_ID = 'docsScrollTop';
const CUSTOM_PURPLE = '#690596';
const CUSTOM_RED = '#e91751';
const CUSTOM_TURQUOIS = '#058789';
-const DOC_JSON_ROOT = constants.S3_SMART_CONTRACTS_DOCUMENTATION_JSON_ROOT;
-const sectionNameToMarkdown = {
- [SmartContractsDocSections.Introduction]: IntroMarkdown,
+const sections = constants.smartContractDocSections;
+
+const docsInfoConfig: DocsInfoConfig = {
+ packageName: '0x Smart Contracts',
+ packageUrl: 'https://github.com/0xProject/contracts',
+ websitePath: WebsitePaths.SmartContracts,
+ docsJsonRoot: 'https://s3.amazonaws.com/smart-contracts-docs-json',
+ menu: {
+ introduction: [
+ sections.Introduction,
+ ],
+ contracts: [
+ sections.Exchange,
+ sections.TokenRegistry,
+ sections.ZRXToken,
+ sections.EtherToken,
+ sections.TokenTransferProxy,
+ ],
+ },
+ sectionNameToMarkdown: {
+ [sections.Introduction]: IntroMarkdown,
+ },
+ sections,
};
+
const networkNameToColor: {[network: string]: string} = {
[Networks.kovan]: CUSTOM_PURPLE,
[Networks.ropsten]: CUSTOM_RED,
@@ -90,6 +114,7 @@ const styles: Styles = {
marginLeft: 20,
},
};
+const docsInfo = new DocsInfo(docsInfoConfig);
export class SmartContractsDocumentation extends
React.Component<SmartContractsDocumentationAllProps, SmartContractsDocumentationState> {
@@ -119,9 +144,10 @@ export class SmartContractsDocumentation extends
location={this.props.location}
docsVersion={this.props.docsVersion}
availableDocVersions={this.props.availableDocVersions}
+ menu={docsInfo.getMenu(this.props.docsVersion)}
menuSubsectionsBySection={menuSubsectionsBySection}
shouldFullWidth={true}
- doc={Docs.SmartContracts}
+ docPath={docsInfo.websitePath}
/>
{_.isUndefined(this.state.docAgnosticFormat) ?
<div
@@ -150,9 +176,9 @@ export class SmartContractsDocumentation extends
<NestedSidebarMenu
selectedVersion={this.props.docsVersion}
versions={this.props.availableDocVersions}
- topLevelMenu={constants.menuSmartContracts}
+ topLevelMenu={docsInfo.getMenu()}
menuSubsectionsBySection={menuSubsectionsBySection}
- doc={Docs.SmartContracts}
+ docPath={docsInfo.websitePath}
/>
</div>
</div>
@@ -162,7 +188,7 @@ export class SmartContractsDocumentation extends
style={styles.mainContainers}
className="absolute"
>
- <div id="smartContractsDocs" />
+ <div id={SCROLL_TOP_ID} />
<h1 className="md-pl2 sm-pl3">
<a href={constants.GITHUB_CONTRACTS_URL} target="_blank">
0x Smart Contracts
@@ -177,19 +203,19 @@ export class SmartContractsDocumentation extends
);
}
private renderDocumentation(): React.ReactNode {
- const subMenus = _.values(constants.menuSmartContracts);
+ const subMenus = _.values(docsInfo.getMenu());
const orderedSectionNames = _.flatten(subMenus);
// Since smart contract method params are all base types, no need to pass
// down the typeDefinitionByName
const typeDefinitionByName = {};
- const sections = _.map(orderedSectionNames, this.renderSection.bind(this, typeDefinitionByName));
+ const renderedSections = _.map(orderedSectionNames, this.renderSection.bind(this, typeDefinitionByName));
- return sections;
+ return renderedSections;
}
private renderSection(typeDefinitionByName: TypeDefinitionByName, sectionName: string): React.ReactNode {
const docSection = this.state.docAgnosticFormat[sectionName];
- const markdownFileIfExists = sectionNameToMarkdown[sectionName];
+ const markdownFileIfExists = docsInfo.sectionNameToMarkdown[sectionName];
if (!_.isUndefined(markdownFileIfExists)) {
return (
<MarkdownSection
@@ -219,6 +245,7 @@ export class SmartContractsDocumentation extends
<EventDefinition
key={`event-${event.name}-${i}`}
event={event}
+ docsInfo={docsInfo}
/>
);
});
@@ -293,7 +320,7 @@ export class SmartContractsDocumentation extends
typeDefinitionByName: TypeDefinitionByName): React.ReactNode {
const constructorDefs = _.map(constructors, constructor => {
return this.renderMethodBlocks(
- constructor, SmartContractsDocSections.zeroEx, constructor.isConstructor, typeDefinitionByName,
+ constructor, docsInfo.sections.zeroEx, constructor.isConstructor, typeDefinitionByName,
);
});
return (
@@ -309,12 +336,13 @@ export class SmartContractsDocumentation extends
className="pb3"
>
<code className="hljs">
- {property.name}: <Type type={property.type} />
+ {property.name}: <Type type={property.type} docsInfo={docsInfo} />
</code>
{property.source &&
<SourceLink
version={this.props.docsVersion}
source={property.source}
+ baseUrl={docsInfo.packageUrl}
/>
}
{property.comment &&
@@ -334,6 +362,7 @@ export class SmartContractsDocumentation extends
method={method}
typeDefinitionByName={typeDefinitionByName}
libraryVersion={this.props.docsVersion}
+ docsInfo={docsInfo}
/>
);
}
@@ -341,7 +370,7 @@ export class SmartContractsDocumentation extends
const hashWithPrefix = this.props.location.hash;
let hash = hashWithPrefix.slice(1);
if (_.isEmpty(hash)) {
- hash = 'smartContractsDocs'; // scroll to the top
+ hash = SCROLL_TOP_ID; // scroll to the top
}
scroller.scrollTo(hash, {duration: 0, offset: 0, containerId: 'documentation'});
@@ -352,14 +381,14 @@ export class SmartContractsDocumentation extends
return menuSubsectionsBySection;
}
- const docSections = _.keys(SmartContractsDocSections);
+ const docSections = _.keys(docsInfo.sections);
_.each(docSections, sectionName => {
const docSection = docAgnosticFormat[sectionName];
if (_.isUndefined(docSection)) {
return; // no-op
}
- if (sectionName === SmartContractsDocSections.types) {
+ if (sectionName === docsInfo.sections.types) {
const sortedTypesNames = _.sortBy(docSection.types, 'name');
const typeNames = _.map(sortedTypesNames, t => t.name);
menuSubsectionsBySection[sectionName] = typeNames;
@@ -374,7 +403,7 @@ export class SmartContractsDocumentation extends
return menuSubsectionsBySection;
}
private async fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists?: string): Promise<void> {
- const versionToFileName = await docUtils.getVersionToFileNameAsync(DOC_JSON_ROOT);
+ const versionToFileName = await docUtils.getVersionToFileNameAsync(docsInfo.docsJsonRoot);
const versions = _.keys(versionToFileName);
this.props.dispatcher.updateAvailableDocVersions(versions);
const sortedVersions = semverSort.desc(versions);
@@ -390,7 +419,7 @@ export class SmartContractsDocumentation extends
this.props.dispatcher.updateCurrentDocsVersion(versionToFetch);
const versionFileNameToFetch = versionToFileName[versionToFetch];
- const versionDocObj = await docUtils.getJSONDocFileAsync(versionFileNameToFetch, DOC_JSON_ROOT);
+ const versionDocObj = await docUtils.getJSONDocFileAsync(versionFileNameToFetch, docsInfo.docsJsonRoot);
const docAgnosticFormat = doxityUtils.convertToDocAgnosticFormat(versionDocObj as DoxityDocObj);
this.setState({
diff --git a/packages/website/ts/pages/documentation/source_link.tsx b/packages/website/ts/pages/documentation/source_link.tsx
index 0d40a4b7a..408dcabc7 100644
--- a/packages/website/ts/pages/documentation/source_link.tsx
+++ b/packages/website/ts/pages/documentation/source_link.tsx
@@ -5,6 +5,7 @@ import {constants} from 'ts/utils/constants';
interface SourceLinkProps {
source: Source;
+ baseUrl: string;
version: string;
}
@@ -12,7 +13,7 @@ const SUB_PKG = '0x.js';
export function SourceLink(props: SourceLinkProps) {
const src = props.source;
- const url = constants.GITHUB_0X_JS_URL;
+ const url = props.baseUrl;
const sourceCodeUrl = `${url}/blob/${SUB_PKG}%40${props.version}/packages/${SUB_PKG}/${src.fileName}#L${src.line}`;
return (
<div className="pt2" style={{fontSize: 14}}>
diff --git a/packages/website/ts/pages/documentation/type.tsx b/packages/website/ts/pages/documentation/type.tsx
index b7d56f360..acd46ab72 100644
--- a/packages/website/ts/pages/documentation/type.tsx
+++ b/packages/website/ts/pages/documentation/type.tsx
@@ -3,6 +3,7 @@ import {colors} from 'material-ui/styles';
import * as React from 'react';
import {Link as ScrollLink} from 'react-scroll';
import * as ReactTooltip from 'react-tooltip';
+import {DocsInfo} from 'ts/pages/documentation/docs_info';
import {TypeDefinition} from 'ts/pages/documentation/type_definition';
import {Type as TypeDef, TypeDefinitionByName, TypeDocTypes} from 'ts/types';
import {constants} from 'ts/utils/constants';
@@ -38,6 +39,7 @@ const typeToSection: {[typeName: string]: string} = {
interface TypeProps {
type: TypeDef;
+ docsInfo: DocsInfo;
typeDefinitionByName?: TypeDefinitionByName;
}
@@ -70,6 +72,7 @@ export function Type(props: TypeProps): any {
key={key}
type={arg.elementType}
typeDefinitionByName={props.typeDefinitionByName}
+ docsInfo={props.docsInfo}
/>[]
</span>
);
@@ -79,6 +82,7 @@ export function Type(props: TypeProps): any {
key={`type-${arg.name}-${arg.value}-${arg.typeDocType}`}
type={arg}
typeDefinitionByName={props.typeDefinitionByName}
+ docsInfo={props.docsInfo}
/>
);
return subType;
@@ -102,6 +106,7 @@ export function Type(props: TypeProps): any {
key={`type-${t.name}-${t.value}-${t.typeDocType}`}
type={t}
typeDefinitionByName={props.typeDefinitionByName}
+ docsInfo={props.docsInfo}
/>
);
});
@@ -141,7 +146,7 @@ export function Type(props: TypeProps): any {
</a>
);
} else if ((isReference || isArray) &&
- (typeDocUtils.isPublicType(typeName as string) ||
+ (props.docsInfo.isPublicType(typeName as string) ||
!_.isUndefined(sectionNameIfExists))) {
const id = Math.random().toString();
const typeDefinitionAnchorId = _.isUndefined(sectionNameIfExists) ? typeName : sectionNameIfExists;
@@ -176,7 +181,11 @@ export function Type(props: TypeProps): any {
id={id}
className="typeTooltip"
>
- <TypeDefinition customType={typeDefinition} shouldAddId={false} />
+ <TypeDefinition
+ customType={typeDefinition}
+ shouldAddId={false}
+ docsInfo={props.docsInfo}
+ />
</ReactTooltip>
</span>
}
diff --git a/packages/website/ts/pages/documentation/type_definition.tsx b/packages/website/ts/pages/documentation/type_definition.tsx
index 984c223b6..17b182c70 100644
--- a/packages/website/ts/pages/documentation/type_definition.tsx
+++ b/packages/website/ts/pages/documentation/type_definition.tsx
@@ -2,6 +2,7 @@ import * as _ from 'lodash';
import * as React from 'react';
import {Comment} from 'ts/pages/documentation/comment';
import {CustomEnum} from 'ts/pages/documentation/custom_enum';
+import {DocsInfo} from 'ts/pages/documentation/docs_info';
import {Enum} from 'ts/pages/documentation/enum';
import {Interface} from 'ts/pages/documentation/interface';
import {MethodSignature} from 'ts/pages/documentation/method_signature';
@@ -17,6 +18,7 @@ const KEYWORD_COLOR = '#a81ca6';
interface TypeDefinitionProps {
customType: CustomType;
shouldAddId?: boolean;
+ docsInfo: DocsInfo;
}
interface TypeDefinitionState {
@@ -35,7 +37,7 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
}
public render() {
const customType = this.props.customType;
- if (!typeDocUtils.isPublicType(customType.name)) {
+ if (!this.props.docsInfo.isPublicType(customType.name)) {
return null; // no-op
}
@@ -47,6 +49,7 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
codeSnippet = (
<Interface
type={customType}
+ docsInfo={this.props.docsInfo}
/>
);
break;
@@ -81,11 +84,12 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
<span>
<span style={{color: KEYWORD_COLOR}}>type</span> {customType.name} ={' '}
{customType.type.typeDocType !== TypeDocTypes.Reflection ?
- <Type type={customType.type} /> :
+ <Type type={customType.type} docsInfo={this.props.docsInfo} /> :
<MethodSignature
method={customType.type.method}
shouldHideMethodName={true}
shouldUseArrowSyntax={true}
+ docsInfo={this.props.docsInfo}
/>
}
</span>
diff --git a/packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx b/packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx
index d64b196ed..5acd99b60 100644
--- a/packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx
+++ b/packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx
@@ -16,6 +16,7 @@ import semverSort = require('semver-sort');
import {TopBar} from 'ts/components/top_bar';
import {Loading} from 'ts/components/ui/loading';
import {Comment} from 'ts/pages/documentation/comment';
+import {DocsInfo} from 'ts/pages/documentation/docs_info';
import {MethodBlock} from 'ts/pages/documentation/method_block';
import {SourceLink} from 'ts/pages/documentation/source_link';
import {Type} from 'ts/pages/documentation/type';
@@ -29,6 +30,7 @@ import {
CustomType,
DocAgnosticFormat,
Docs,
+ DocsInfoConfig,
KindString,
Property,
ScreenWidths,
@@ -36,7 +38,7 @@ import {
TypeDefinitionByName,
TypeDocNode,
TypescriptMethod,
- ZeroExJsDocSections,
+ WebsitePaths,
} from 'ts/types';
import {constants} from 'ts/utils/constants';
import {docUtils} from 'ts/utils/doc_utils';
@@ -51,16 +53,127 @@ const versioningMarkdown = require('md/docs/0xjs/versioning');
/* tslint:enable:no-var-requires */
const SCROLL_TO_TIMEOUT = 500;
-const DOC_JSON_ROOT = constants.S3_0XJS_DOCUMENTATION_JSON_ROOT;
+const SCROLL_TOP_ID = 'docsScrollTop';
-const sectionNameToMarkdown = {
- [ZeroExJsDocSections.introduction]: IntroMarkdown,
- [ZeroExJsDocSections.installation]: InstallationMarkdown,
- [ZeroExJsDocSections.async]: AsyncMarkdown,
- [ZeroExJsDocSections.errors]: ErrorsMarkdown,
- [ZeroExJsDocSections.versioning]: versioningMarkdown,
+const zeroExJsDocSections = {
+ introduction: 'introduction',
+ installation: 'installation',
+ testrpc: 'testrpc',
+ async: 'async',
+ errors: 'errors',
+ versioning: 'versioning',
+ zeroEx: 'zeroEx',
+ exchange: 'exchange',
+ token: 'token',
+ tokenRegistry: 'tokenRegistry',
+ etherToken: 'etherToken',
+ proxy: 'proxy',
+ types: 'types',
};
+const docsInfoConfig: DocsInfoConfig = {
+ packageName: '0x.js',
+ packageUrl: 'https://github.com/0xProject/0x.js',
+ websitePath: WebsitePaths.ZeroExJs,
+ docsJsonRoot: 'https://s3.amazonaws.com/0xjs-docs-jsons',
+ menu: {
+ introduction: [
+ zeroExJsDocSections.introduction,
+ ],
+ install: [
+ zeroExJsDocSections.installation,
+ ],
+ topics: [
+ zeroExJsDocSections.async,
+ zeroExJsDocSections.errors,
+ zeroExJsDocSections.versioning,
+ ],
+ zeroEx: [
+ zeroExJsDocSections.zeroEx,
+ ],
+ contracts: [
+ zeroExJsDocSections.exchange,
+ zeroExJsDocSections.token,
+ zeroExJsDocSections.tokenRegistry,
+ zeroExJsDocSections.etherToken,
+ zeroExJsDocSections.proxy,
+ ],
+ types: [
+ zeroExJsDocSections.types,
+ ],
+ },
+ sectionNameToMarkdown: {
+ [zeroExJsDocSections.introduction]: IntroMarkdown,
+ [zeroExJsDocSections.installation]: InstallationMarkdown,
+ [zeroExJsDocSections.async]: AsyncMarkdown,
+ [zeroExJsDocSections.errors]: ErrorsMarkdown,
+ [zeroExJsDocSections.versioning]: versioningMarkdown,
+ },
+ // 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: [
+ 'Order',
+ 'SignedOrder',
+ 'ECSignature',
+ 'ZeroExError',
+ 'EventCallback',
+ 'EventCallbackAsync',
+ 'EventCallbackSync',
+ 'ExchangeContractErrs',
+ 'ContractEvent',
+ 'Token',
+ 'ExchangeEvents',
+ 'IndexedFilterValues',
+ 'SubscriptionOpts',
+ 'BlockParam',
+ 'OrderFillOrKillRequest',
+ 'OrderCancellationRequest',
+ 'OrderFillRequest',
+ 'ContractEventEmitter',
+ 'Web3Provider',
+ 'ContractEventArgs',
+ 'LogCancelArgs',
+ 'LogFillArgs',
+ 'LogErrorContractEventArgs',
+ 'LogFillContractEventArgs',
+ 'LogCancelContractEventArgs',
+ 'TokenEvents',
+ 'ExchangeContractEventArgs',
+ 'TransferContractEventArgs',
+ 'ApprovalContractEventArgs',
+ 'TokenContractEventArgs',
+ 'ZeroExConfig',
+ 'TransactionReceiptWithDecodedLogs',
+ 'LogWithDecodedArgs',
+ 'DecodedLogArgs',
+ 'MethodOpts',
+ 'ValidateOrderFillableOpts',
+ 'OrderTransactionOpts',
+ 'ContractEventArg',
+ 'LogEvent',
+ 'LogEntry',
+ 'DecodedLogEvent',
+ ],
+ sectionNameToModulePath: {
+ [zeroExJsDocSections.zeroEx]: ['"src/0x"'],
+ [zeroExJsDocSections.exchange]: ['"src/contract_wrappers/exchange_wrapper"'],
+ [zeroExJsDocSections.tokenRegistry]: ['"src/contract_wrappers/token_registry_wrapper"'],
+ [zeroExJsDocSections.token]: ['"src/contract_wrappers/token_wrapper"'],
+ [zeroExJsDocSections.etherToken]: ['"src/contract_wrappers/ether_token_wrapper"'],
+ [zeroExJsDocSections.proxy]: [
+ '"src/contract_wrappers/proxy_wrapper"',
+ '"src/contract_wrappers/token_transfer_proxy_wrapper"',
+ ],
+ [zeroExJsDocSections.types]: ['"src/types"'],
+ },
+ menuSubsectionToVersionWhenIntroduced: {
+ [zeroExJsDocSections.etherToken]: '0.7.1',
+ [zeroExJsDocSections.proxy]: '0.8.0',
+ },
+ sections: zeroExJsDocSections,
+};
+const docsInfo = new DocsInfo(docsInfoConfig);
+
export interface ZeroExJSDocumentationPassedProps {
source: string;
location: Location;
@@ -113,20 +226,21 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
this.fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists);
}
public render() {
- const menuSubsectionsBySection = _.isUndefined(this.state.docAgnosticFormat)
- ? {}
- : typeDocUtils.getMenuSubsectionsBySection(this.state.docAgnosticFormat);
+ const menuSubsectionsBySection = _.isUndefined(this.state.docAgnosticFormat) ?
+ {} :
+ typeDocUtils.getMenuSubsectionsBySection(docsInfo.sections, this.state.docAgnosticFormat);
return (
<div>
- <DocumentTitle title="0x.js Documentation"/>
+ <DocumentTitle title={`${docsInfo.packageName} Documentation`}/>
<TopBar
blockchainIsLoaded={false}
location={this.props.location}
docsVersion={this.props.docsVersion}
availableDocVersions={this.props.availableDocVersions}
+ menu={docsInfo.getMenu(this.props.docsVersion)}
menuSubsectionsBySection={menuSubsectionsBySection}
shouldFullWidth={true}
- doc={Docs.ZeroExJs}
+ docPath={docsInfo.websitePath}
/>
{_.isUndefined(this.state.docAgnosticFormat) ?
<div
@@ -155,9 +269,9 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
<NestedSidebarMenu
selectedVersion={this.props.docsVersion}
versions={this.props.availableDocVersions}
- topLevelMenu={typeDocUtils.getFinal0xjsMenu(this.props.docsVersion)}
+ topLevelMenu={docsInfo.getMenu(this.props.docsVersion)}
menuSubsectionsBySection={menuSubsectionsBySection}
- doc={Docs.ZeroExJs}
+ docPath={docsInfo.websitePath}
/>
</div>
</div>
@@ -167,10 +281,10 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
style={styles.mainContainers}
className="absolute"
>
- <div id="zeroExJSDocs" />
+ <div id={SCROLL_TOP_ID} />
<h1 className="md-pl2 sm-pl3">
- <a href={constants.GITHUB_0X_JS_URL} target="_blank">
- 0x.js
+ <a href={docsInfo.packageUrl} target="_blank">
+ {docsInfo.packageName}
</a>
</h1>
{this.renderDocumentation()}
@@ -182,10 +296,10 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
);
}
private renderDocumentation(): React.ReactNode {
- const typeDocSection = this.state.docAgnosticFormat[ZeroExJsDocSections.types];
+ const typeDocSection = this.state.docAgnosticFormat[docsInfo.sections.types];
const typeDefinitionByName = _.keyBy(typeDocSection.types, 'name');
- const subMenus = _.values(constants.menu0xjs);
+ const subMenus = _.values(docsInfo.getMenu());
const orderedSectionNames = _.flatten(subMenus);
const sections = _.map(orderedSectionNames, this.renderSection.bind(this, typeDefinitionByName));
@@ -194,7 +308,7 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
private renderSection(typeDefinitionByName: TypeDefinitionByName, sectionName: string): React.ReactNode {
const docSection = this.state.docAgnosticFormat[sectionName];
- const markdownFileIfExists = sectionNameToMarkdown[sectionName];
+ const markdownFileIfExists = docsInfo.sectionNameToMarkdown[sectionName];
if (!_.isUndefined(markdownFileIfExists)) {
return (
<MarkdownSection
@@ -214,6 +328,7 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
<TypeDefinition
key={`type-${customType.name}`}
customType={customType}
+ docsInfo={docsInfo}
/>
);
});
@@ -231,7 +346,7 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
<Comment
comment={docSection.comment}
/>
- {sectionName === ZeroExJsDocSections.zeroEx && docSection.constructors.length > 0 &&
+ {sectionName === docsInfo.sections.zeroEx && docSection.constructors.length > 0 &&
<div>
<h2 className="thin">Constructor</h2>
{this.renderZeroExConstructors(docSection.constructors, typeDefinitionByName)}
@@ -261,7 +376,7 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
typeDefinitionByName: TypeDefinitionByName): React.ReactNode {
const constructorDefs = _.map(constructors, constructor => {
return this.renderMethodBlocks(
- constructor, ZeroExJsDocSections.zeroEx, constructor.isConstructor, typeDefinitionByName,
+ constructor, docsInfo.sections.zeroEx, constructor.isConstructor, typeDefinitionByName,
);
});
return (
@@ -277,11 +392,12 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
className="pb3"
>
<code className="hljs">
- {property.name}: <Type type={property.type} />
+ {property.name}: <Type type={property.type} docsInfo={docsInfo} />
</code>
<SourceLink
version={this.props.docsVersion}
source={property.source}
+ baseUrl={docsInfo.packageUrl}
/>
{property.comment &&
<Comment
@@ -300,6 +416,7 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
method={method}
typeDefinitionByName={typeDefinitionByName}
libraryVersion={this.props.docsVersion}
+ docsInfo={docsInfo}
/>
);
}
@@ -307,13 +424,13 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
const hashWithPrefix = this.props.location.hash;
let hash = hashWithPrefix.slice(1);
if (_.isEmpty(hash)) {
- hash = 'zeroExJSDocs'; // scroll to the top
+ hash = SCROLL_TOP_ID; // scroll to the top
}
scroller.scrollTo(hash, {duration: 0, offset: 0, containerId: 'documentation'});
}
private async fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists?: string): Promise<void> {
- const versionToFileName = await docUtils.getVersionToFileNameAsync(DOC_JSON_ROOT);
+ const versionToFileName = await docUtils.getVersionToFileNameAsync(docsInfo.docsJsonRoot);
const versions = _.keys(versionToFileName);
this.props.dispatcher.updateAvailableDocVersions(versions);
const sortedVersions = semverSort.desc(versions);
@@ -329,8 +446,12 @@ export class ZeroExJSDocumentation extends React.Component<ZeroExJSDocumentation
this.props.dispatcher.updateCurrentDocsVersion(versionToFetch);
const versionFileNameToFetch = versionToFileName[versionToFetch];
- const versionDocObj = await docUtils.getJSONDocFileAsync(versionFileNameToFetch, DOC_JSON_ROOT);
- const docAgnosticFormat = typeDocUtils.convertToDocAgnosticFormat((versionDocObj as TypeDocNode));
+ const versionDocObj = await docUtils.getJSONDocFileAsync(
+ versionFileNameToFetch, docsInfo.docsJsonRoot,
+ );
+ const docAgnosticFormat = typeDocUtils.convertToDocAgnosticFormat(
+ docsInfo, (versionDocObj as TypeDocNode),
+ );
this.setState({
docAgnosticFormat,