From 72a00ac2df47ff793d74c2a82c7f403f501e784a Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Tue, 28 Nov 2017 15:11:04 -0600 Subject: Refactor the topLevel documentation react components for 0x.js and Smart contracts into a single component --- .../website/ts/pages/documentation/docs_info.ts | 55 ++- .../ts/pages/documentation/documentation.tsx | 398 ++++++++++++++++++ .../smart_contracts_documentation.tsx | 431 ------------------- .../documentation/zero_ex_js_documentation.tsx | 462 --------------------- 4 files changed, 452 insertions(+), 894 deletions(-) create mode 100644 packages/website/ts/pages/documentation/documentation.tsx delete mode 100644 packages/website/ts/pages/documentation/smart_contracts_documentation.tsx delete mode 100644 packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx (limited to 'packages/website/ts/pages/documentation') diff --git a/packages/website/ts/pages/documentation/docs_info.ts b/packages/website/ts/pages/documentation/docs_info.ts index 326ebb31c..f607c2185 100644 --- a/packages/website/ts/pages/documentation/docs_info.ts +++ b/packages/website/ts/pages/documentation/docs_info.ts @@ -1,6 +1,14 @@ import compareVersions = require('compare-versions'); import * as _ from 'lodash'; -import {DocsInfoConfig, DocsMenu, SectionsMap} from 'ts/types'; +import { + DocAgnosticFormat, + DocsInfoConfig, + DocsMenu, + DoxityDocObj, + MenuSubsectionsBySection, + SectionsMap, + TypeDocNode, +} from 'ts/types'; export class DocsInfo { public packageName: string; @@ -49,4 +57,49 @@ export class DocsInfo { }); return finalMenu; } + public getMenuSubsectionsBySection(docAgnosticFormat?: DocAgnosticFormat): MenuSubsectionsBySection { + const menuSubsectionsBySection = {} as MenuSubsectionsBySection; + if (_.isUndefined(docAgnosticFormat)) { + return menuSubsectionsBySection; + } + + const docSections = _.keys(this.sections); + _.each(docSections, sectionName => { + const docSection = docAgnosticFormat[sectionName]; + if (_.isUndefined(docSection)) { + return; // no-op + } + + if (!_.isUndefined(this.sections.types) && sectionName === this.sections.types) { + const sortedTypesNames = _.sortBy(docSection.types, 'name'); + const typeNames = _.map(sortedTypesNames, t => t.name); + menuSubsectionsBySection[sectionName] = typeNames; + } else { + let eventNames: string[] = []; + if (!_.isUndefined(docSection.events)) { + const sortedEventNames = _.sortBy(docSection.events, 'name'); + eventNames = _.map(sortedEventNames, m => m.name); + } + const sortedMethodNames = _.sortBy(docSection.methods, 'name'); + const methodNames = _.map(sortedMethodNames, m => m.name); + menuSubsectionsBySection[sectionName] = [...methodNames, ...eventNames]; + } + }); + return menuSubsectionsBySection; + } + public getTypeDefinitionsByName(docAgnosticFormat: DocAgnosticFormat) { + if (_.isUndefined(this.sections.types)) { + return {}; + } + + const typeDocSection = docAgnosticFormat[this.sections.types]; + const typeDefinitionByName = _.keyBy(typeDocSection.types, 'name'); + return typeDefinitionByName; + } + public isVisibleConstructor(sectionName: string): boolean { + return _.includes(this.docsInfo.visibleConstructors, sectionName); + } + public convertToDocAgnosticFormat(docObj: DoxityDocObj|TypeDocNode): DocAgnosticFormat { + return this.docsInfo.convertToDocAgnosticFormatFn(docObj, this); + } } diff --git a/packages/website/ts/pages/documentation/documentation.tsx b/packages/website/ts/pages/documentation/documentation.tsx new file mode 100644 index 000000000..288a8f79c --- /dev/null +++ b/packages/website/ts/pages/documentation/documentation.tsx @@ -0,0 +1,398 @@ +import findVersions = require('find-versions'); +import * as _ from 'lodash'; +import CircularProgress from 'material-ui/CircularProgress'; +import {colors} from 'material-ui/styles'; +import * as React from 'react'; +import DocumentTitle = require('react-document-title'); +import { + scroller, +} from 'react-scroll'; +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'; +import {Type} from 'ts/pages/documentation/type'; +import {TypeDefinition} from 'ts/pages/documentation/type_definition'; +import {AnchorTitle} from 'ts/pages/shared/anchor_title'; +import {MarkdownSection} from 'ts/pages/shared/markdown_section'; +import {NestedSidebarMenu} from 'ts/pages/shared/nested_sidebar_menu'; +import {SectionHeader} from 'ts/pages/shared/section_header'; +import {Dispatcher} from 'ts/redux/dispatcher'; +import { + AddressByContractName, + CustomType, + DocAgnosticFormat, + Docs, + DocsInfoConfig, + DoxityDocObj, + EtherscanLinkSuffixes, + Event, + MenuSubsectionsBySection, + Networks, + Property, + SolidityMethod, + Styles, + TypeDefinitionByName, + TypeDocNode, + TypescriptMethod, + WebsitePaths, +} from 'ts/types'; +import {constants} from 'ts/utils/constants'; +import {docUtils} from 'ts/utils/doc_utils'; +import {utils} from 'ts/utils/utils'; + +const SCROLL_TO_TIMEOUT = 500; +const SCROLL_TOP_ID = 'docsScrollTop'; +const CUSTOM_PURPLE = '#690596'; +const CUSTOM_RED = '#e91751'; +const CUSTOM_TURQUOIS = '#058789'; + +const networkNameToColor: {[network: string]: string} = { + [Networks.kovan]: CUSTOM_PURPLE, + [Networks.ropsten]: CUSTOM_RED, + [Networks.mainnet]: CUSTOM_TURQUOIS, +}; + +export interface DocumentationAllProps { + source: string; + location: Location; + dispatcher: Dispatcher; + docsVersion: string; + availableDocVersions: string[]; + docsInfo: DocsInfo; +} + +interface DocumentationState { + docAgnosticFormat?: DocAgnosticFormat; +} + +const styles: Styles = { + mainContainers: { + position: 'absolute', + top: 60, + left: 0, + bottom: 0, + right: 0, + overflowZ: 'hidden', + overflowY: 'scroll', + minHeight: 'calc(100vh - 60px)', + WebkitOverflowScrolling: 'touch', + }, + menuContainer: { + borderColor: colors.grey300, + maxWidth: 330, + marginLeft: 20, + }, +}; + +export class Documentation extends + React.Component { + constructor(props: DocumentationAllProps) { + super(props); + this.state = { + docAgnosticFormat: undefined, + }; + } + public componentWillMount() { + const pathName = this.props.location.pathname; + const lastSegment = pathName.substr(pathName.lastIndexOf('/') + 1); + const versions = findVersions(lastSegment); + const preferredVersionIfExists = versions.length > 0 ? versions[0] : undefined; + // tslint:disable-next-line:no-floating-promises + this.fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists); + } + public render() { + const menuSubsectionsBySection = _.isUndefined(this.state.docAgnosticFormat) ? + {} : + this.props.docsInfo.getMenuSubsectionsBySection(this.state.docAgnosticFormat); + return ( +
+ + + {_.isUndefined(this.state.docAgnosticFormat) ? +
+
+
+ +
+
Loading documentation...
+
+
: +
+
+
+ +
+
+
+
+
+

+ + {this.props.docsInfo.packageName} + +

+ {this.renderDocumentation()} +
+
+
+ } +
+ ); + } + private renderDocumentation(): React.ReactNode { + const subMenus = _.values(this.props.docsInfo.getMenu()); + const orderedSectionNames = _.flatten(subMenus); + + const typeDefinitionByName = this.props.docsInfo.getTypeDefinitionsByName(this.state.docAgnosticFormat); + const renderedSections = _.map(orderedSectionNames, this.renderSection.bind(this, typeDefinitionByName)); + + return renderedSections; + } + private renderSection(typeDefinitionByName: TypeDefinitionByName, sectionName: string): React.ReactNode { + const markdownFileIfExists = this.props.docsInfo.sectionNameToMarkdown[sectionName]; + if (!_.isUndefined(markdownFileIfExists)) { + return ( + + ); + } + + const docSection = this.state.docAgnosticFormat[sectionName]; + if (_.isUndefined(docSection)) { + return null; + } + + const sortedTypes = _.sortBy(docSection.types, 'name'); + const typeDefs = _.map(sortedTypes, customType => { + return ( + + ); + }); + + const sortedProperties = _.sortBy(docSection.properties, 'name'); + const propertyDefs = _.map(sortedProperties, this.renderProperty.bind(this)); + + const sortedMethods = _.sortBy(docSection.methods, 'name'); + const methodDefs = _.map(sortedMethods, method => { + const isConstructor = false; + return this.renderMethodBlocks(method, sectionName, isConstructor, typeDefinitionByName); + }); + + const sortedEvents = _.sortBy(docSection.events, 'name'); + const eventDefs = _.map(sortedEvents, (event: Event, i: number) => { + return ( + + ); + }); + return ( +
+
+
+ +
+ {this.renderNetworkBadgesIfExists(sectionName)} +
+ {docSection.comment && + + } + {docSection.constructors.length > 0 && + this.props.docsInfo.isVisibleConstructor(sectionName) && +
+

Constructor

+ {this.renderConstructors(docSection.constructors, sectionName, typeDefinitionByName)} +
+ } + {docSection.properties.length > 0 && +
+

Properties

+
{propertyDefs}
+
+ } + {docSection.methods.length > 0 && +
+

Methods

+
{methodDefs}
+
+ } + {!_.isUndefined(docSection.events) && docSection.events.length > 0 && +
+

Events

+
{eventDefs}
+
+ } + {!_.isUndefined(typeDefs) && typeDefs.length > 0 && +
+
{typeDefs}
+
+ } +
+ ); + } + private renderNetworkBadgesIfExists(sectionName: string) { + const networkToAddressByContractName = constants.contractAddresses[this.props.docsVersion]; + const badges = _.map(networkToAddressByContractName, + (addressByContractName: AddressByContractName, networkName: string) => { + const contractAddress = addressByContractName[sectionName]; + if (_.isUndefined(contractAddress)) { + return null; + } + const linkIfExists = utils.getEtherScanLinkIfExists( + contractAddress, constants.networkIdByName[networkName], EtherscanLinkSuffixes.address, + ); + return ( + + + + ); + }); + return badges; + } + private renderConstructors(constructors: SolidityMethod[]|TypescriptMethod[], + sectionName: string, + typeDefinitionByName: TypeDefinitionByName): React.ReactNode { + const constructorDefs = _.map(constructors, constructor => { + return this.renderMethodBlocks( + constructor, sectionName, constructor.isConstructor, typeDefinitionByName, + ); + }); + return ( +
+ {constructorDefs} +
+ ); + } + private renderProperty(property: Property): React.ReactNode { + return ( +
+ + {property.name}: + + {property.source && + + } + {property.comment && + + } +
+ ); + } + private renderMethodBlocks(method: SolidityMethod|TypescriptMethod, sectionName: string, + isConstructor: boolean, typeDefinitionByName: TypeDefinitionByName): React.ReactNode { + return ( + + ); + } + private scrollToHash(): void { + const hashWithPrefix = this.props.location.hash; + let hash = hashWithPrefix.slice(1); + if (_.isEmpty(hash)) { + hash = SCROLL_TOP_ID; // scroll to the top + } + + scroller.scrollTo(hash, {duration: 0, offset: 0, containerId: 'documentation'}); + } + private async fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists?: string): Promise { + const versionToFileName = await docUtils.getVersionToFileNameAsync(this.props.docsInfo.docsJsonRoot); + const versions = _.keys(versionToFileName); + this.props.dispatcher.updateAvailableDocVersions(versions); + const sortedVersions = semverSort.desc(versions); + const latestVersion = sortedVersions[0]; + + let versionToFetch = latestVersion; + if (!_.isUndefined(preferredVersionIfExists)) { + const preferredVersionFileNameIfExists = versionToFileName[preferredVersionIfExists]; + if (!_.isUndefined(preferredVersionFileNameIfExists)) { + versionToFetch = preferredVersionIfExists; + } + } + this.props.dispatcher.updateCurrentDocsVersion(versionToFetch); + + const versionFileNameToFetch = versionToFileName[versionToFetch]; + const versionDocObj = await docUtils.getJSONDocFileAsync( + versionFileNameToFetch, this.props.docsInfo.docsJsonRoot, + ); + const docAgnosticFormat = this.props.docsInfo.convertToDocAgnosticFormat(versionDocObj as DoxityDocObj); + + this.setState({ + docAgnosticFormat, + }, () => { + this.scrollToHash(); + }); + } +} diff --git a/packages/website/ts/pages/documentation/smart_contracts_documentation.tsx b/packages/website/ts/pages/documentation/smart_contracts_documentation.tsx deleted file mode 100644 index c7104e150..000000000 --- a/packages/website/ts/pages/documentation/smart_contracts_documentation.tsx +++ /dev/null @@ -1,431 +0,0 @@ -import findVersions = require('find-versions'); -import * as _ from 'lodash'; -import CircularProgress from 'material-ui/CircularProgress'; -import {colors} from 'material-ui/styles'; -import * as React from 'react'; -import DocumentTitle = require('react-document-title'); -import { - scroller, -} from 'react-scroll'; -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'; -import {Type} from 'ts/pages/documentation/type'; -import {TypeDefinition} from 'ts/pages/documentation/type_definition'; -import {AnchorTitle} from 'ts/pages/shared/anchor_title'; -import {MarkdownSection} from 'ts/pages/shared/markdown_section'; -import {NestedSidebarMenu} from 'ts/pages/shared/nested_sidebar_menu'; -import {SectionHeader} from 'ts/pages/shared/section_header'; -import {Dispatcher} from 'ts/redux/dispatcher'; -import { - AddressByContractName, - CustomType, - DocAgnosticFormat, - Docs, - DocsInfoConfig, - DoxityDocObj, - EtherscanLinkSuffixes, - Event, - MenuSubsectionsBySection, - Networks, - Property, - SolidityMethod, - Styles, - TypeDefinitionByName, - WebsitePaths, -} from 'ts/types'; -import {constants} from 'ts/utils/constants'; -import {docUtils} from 'ts/utils/doc_utils'; -import {doxityUtils} from 'ts/utils/doxity_utils'; -import {utils} from 'ts/utils/utils'; -/* tslint:disable:no-var-requires */ -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 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, - [Networks.mainnet]: CUSTOM_TURQUOIS, -}; - -export interface SmartContractsDocumentationAllProps { - source: string; - location: Location; - dispatcher: Dispatcher; - docsVersion: string; - availableDocVersions: string[]; -} - -interface SmartContractsDocumentationState { - docAgnosticFormat?: DocAgnosticFormat; -} - -const styles: Styles = { - mainContainers: { - position: 'absolute', - top: 60, - left: 0, - bottom: 0, - right: 0, - overflowZ: 'hidden', - overflowY: 'scroll', - minHeight: 'calc(100vh - 60px)', - WebkitOverflowScrolling: 'touch', - }, - menuContainer: { - borderColor: colors.grey300, - maxWidth: 330, - marginLeft: 20, - }, -}; -const docsInfo = new DocsInfo(docsInfoConfig); - -export class SmartContractsDocumentation extends - React.Component { - constructor(props: SmartContractsDocumentationAllProps) { - super(props); - this.state = { - docAgnosticFormat: undefined, - }; - } - public componentWillMount() { - const pathName = this.props.location.pathname; - const lastSegment = pathName.substr(pathName.lastIndexOf('/') + 1); - const versions = findVersions(lastSegment); - const preferredVersionIfExists = versions.length > 0 ? versions[0] : undefined; - // tslint:disable-next-line:no-floating-promises - this.fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists); - } - public render() { - const menuSubsectionsBySection = _.isUndefined(this.state.docAgnosticFormat) - ? {} - : this.getMenuSubsectionsBySection(this.state.docAgnosticFormat); - return ( -
- - - {_.isUndefined(this.state.docAgnosticFormat) ? -
-
-
- -
-
Loading documentation...
-
-
: -
-
-
- -
-
-
-
-
-

- - 0x Smart Contracts - -

- {this.renderDocumentation()} -
-
-
- } -
- ); - } - private renderDocumentation(): React.ReactNode { - 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 renderedSections = _.map(orderedSectionNames, this.renderSection.bind(this, typeDefinitionByName)); - - return renderedSections; - } - private renderSection(typeDefinitionByName: TypeDefinitionByName, sectionName: string): React.ReactNode { - const docSection = this.state.docAgnosticFormat[sectionName]; - - const markdownFileIfExists = docsInfo.sectionNameToMarkdown[sectionName]; - if (!_.isUndefined(markdownFileIfExists)) { - return ( - - ); - } - - if (_.isUndefined(docSection)) { - return null; - } - - const sortedProperties = _.sortBy(docSection.properties, 'name'); - const propertyDefs = _.map(sortedProperties, this.renderProperty.bind(this)); - - const sortedMethods = _.sortBy(docSection.methods, 'name'); - const methodDefs = _.map(sortedMethods, method => { - const isConstructor = false; - return this.renderMethodBlocks(method, sectionName, isConstructor, typeDefinitionByName); - }); - - const sortedEvents = _.sortBy(docSection.events, 'name'); - const eventDefs = _.map(sortedEvents, (event: Event, i: number) => { - return ( - - ); - }); - return ( -
-
-
- -
- {this.renderNetworkBadges(sectionName)} -
- {docSection.comment && - - } - {docSection.constructors.length > 0 && -
-

Constructor

- {this.renderConstructors(docSection.constructors, typeDefinitionByName)} -
- } - {docSection.properties.length > 0 && -
-

Properties

-
{propertyDefs}
-
- } - {docSection.methods.length > 0 && -
-

Methods

-
{methodDefs}
-
- } - {docSection.events.length > 0 && -
-

Events

-
{eventDefs}
-
- } -
- ); - } - private renderNetworkBadges(sectionName: string) { - const networkToAddressByContractName = constants.contractAddresses[this.props.docsVersion]; - const badges = _.map(networkToAddressByContractName, - (addressByContractName: AddressByContractName, networkName: string) => { - const contractAddress = addressByContractName[sectionName]; - const linkIfExists = utils.getEtherScanLinkIfExists( - contractAddress, constants.networkIdByName[networkName], EtherscanLinkSuffixes.address, - ); - return ( - - - - ); - }); - return badges; - } - private renderConstructors(constructors: SolidityMethod[], - typeDefinitionByName: TypeDefinitionByName): React.ReactNode { - const constructorDefs = _.map(constructors, constructor => { - return this.renderMethodBlocks( - constructor, docsInfo.sections.zeroEx, constructor.isConstructor, typeDefinitionByName, - ); - }); - return ( -
- {constructorDefs} -
- ); - } - private renderProperty(property: Property): React.ReactNode { - return ( -
- - {property.name}: - - {property.source && - - } - {property.comment && - - } -
- ); - } - private renderMethodBlocks(method: SolidityMethod, sectionName: string, isConstructor: boolean, - typeDefinitionByName: TypeDefinitionByName): React.ReactNode { - return ( - - ); - } - private scrollToHash(): void { - const hashWithPrefix = this.props.location.hash; - let hash = hashWithPrefix.slice(1); - if (_.isEmpty(hash)) { - hash = SCROLL_TOP_ID; // scroll to the top - } - - scroller.scrollTo(hash, {duration: 0, offset: 0, containerId: 'documentation'}); - } - private getMenuSubsectionsBySection(docAgnosticFormat?: DocAgnosticFormat): MenuSubsectionsBySection { - const menuSubsectionsBySection = {} as MenuSubsectionsBySection; - if (_.isUndefined(docAgnosticFormat)) { - return menuSubsectionsBySection; - } - - const docSections = _.keys(docsInfo.sections); - _.each(docSections, sectionName => { - const docSection = docAgnosticFormat[sectionName]; - if (_.isUndefined(docSection)) { - return; // no-op - } - - if (sectionName === docsInfo.sections.types) { - const sortedTypesNames = _.sortBy(docSection.types, 'name'); - const typeNames = _.map(sortedTypesNames, t => t.name); - menuSubsectionsBySection[sectionName] = typeNames; - } else { - const sortedEventNames = _.sortBy(docSection.events, 'name'); - const eventNames = _.map(sortedEventNames, m => m.name); - const sortedMethodNames = _.sortBy(docSection.methods, 'name'); - const methodNames = _.map(sortedMethodNames, m => m.name); - menuSubsectionsBySection[sectionName] = [...methodNames, ...eventNames]; - } - }); - return menuSubsectionsBySection; - } - private async fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists?: string): Promise { - const versionToFileName = await docUtils.getVersionToFileNameAsync(docsInfo.docsJsonRoot); - const versions = _.keys(versionToFileName); - this.props.dispatcher.updateAvailableDocVersions(versions); - const sortedVersions = semverSort.desc(versions); - const latestVersion = sortedVersions[0]; - - let versionToFetch = latestVersion; - if (!_.isUndefined(preferredVersionIfExists)) { - const preferredVersionFileNameIfExists = versionToFileName[preferredVersionIfExists]; - if (!_.isUndefined(preferredVersionFileNameIfExists)) { - versionToFetch = preferredVersionIfExists; - } - } - this.props.dispatcher.updateCurrentDocsVersion(versionToFetch); - - const versionFileNameToFetch = versionToFileName[versionToFetch]; - const versionDocObj = await docUtils.getJSONDocFileAsync(versionFileNameToFetch, docsInfo.docsJsonRoot); - const docAgnosticFormat = doxityUtils.convertToDocAgnosticFormat(versionDocObj as DoxityDocObj); - - this.setState({ - docAgnosticFormat, - }, () => { - this.scrollToHash(); - }); - } -} diff --git a/packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx b/packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx deleted file mode 100644 index 5acd99b60..000000000 --- a/packages/website/ts/pages/documentation/zero_ex_js_documentation.tsx +++ /dev/null @@ -1,462 +0,0 @@ -import findVersions = require('find-versions'); -import * as _ from 'lodash'; -import CircularProgress from 'material-ui/CircularProgress'; -import MenuItem from 'material-ui/MenuItem'; -import Paper from 'material-ui/Paper'; -import {colors} from 'material-ui/styles'; -import * as React from 'react'; -import DocumentTitle = require('react-document-title'); -import * as ReactMarkdown from 'react-markdown'; -import { - Element as ScrollElement, - Link as ScrollLink, - scroller, -} from 'react-scroll'; -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'; -import {TypeDefinition} from 'ts/pages/documentation/type_definition'; -import {AnchorTitle} from 'ts/pages/shared/anchor_title'; -import {MarkdownSection} from 'ts/pages/shared/markdown_section'; -import {NestedSidebarMenu} from 'ts/pages/shared/nested_sidebar_menu'; -import {SectionHeader} from 'ts/pages/shared/section_header'; -import {Dispatcher} from 'ts/redux/dispatcher'; -import { - CustomType, - DocAgnosticFormat, - Docs, - DocsInfoConfig, - KindString, - Property, - ScreenWidths, - Styles, - TypeDefinitionByName, - TypeDocNode, - TypescriptMethod, - WebsitePaths, -} from 'ts/types'; -import {constants} from 'ts/utils/constants'; -import {docUtils} from 'ts/utils/doc_utils'; -import {typeDocUtils} from 'ts/utils/typedoc_utils'; -import {utils} from 'ts/utils/utils'; -/* tslint:disable:no-var-requires */ -const IntroMarkdown = require('md/docs/0xjs/introduction'); -const InstallationMarkdown = require('md/docs/0xjs/installation'); -const AsyncMarkdown = require('md/docs/0xjs/async'); -const ErrorsMarkdown = require('md/docs/0xjs/errors'); -const versioningMarkdown = require('md/docs/0xjs/versioning'); -/* tslint:enable:no-var-requires */ - -const SCROLL_TO_TIMEOUT = 500; -const SCROLL_TOP_ID = 'docsScrollTop'; - -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; -} - -export interface ZeroExJSDocumentationAllProps { - source: string; - location: Location; - dispatcher: Dispatcher; - docsVersion: string; - availableDocVersions: string[]; -} - -interface ZeroExJSDocumentationState { - docAgnosticFormat?: DocAgnosticFormat; -} - -const styles: Styles = { - mainContainers: { - position: 'absolute', - top: 60, - left: 0, - bottom: 0, - right: 0, - overflowZ: 'hidden', - overflowY: 'scroll', - minHeight: 'calc(100vh - 60px)', - WebkitOverflowScrolling: 'touch', - }, - menuContainer: { - borderColor: colors.grey300, - maxWidth: 330, - marginLeft: 20, - }, -}; - -export class ZeroExJSDocumentation extends React.Component { - constructor(props: ZeroExJSDocumentationAllProps) { - super(props); - this.state = { - docAgnosticFormat: undefined, - }; - } - public componentWillMount() { - const pathName = this.props.location.pathname; - const lastSegment = pathName.substr(pathName.lastIndexOf('/') + 1); - const versions = findVersions(lastSegment); - const preferredVersionIfExists = versions.length > 0 ? versions[0] : undefined; - // tslint:disable-next-line:no-floating-promises - this.fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists); - } - public render() { - const menuSubsectionsBySection = _.isUndefined(this.state.docAgnosticFormat) ? - {} : - typeDocUtils.getMenuSubsectionsBySection(docsInfo.sections, this.state.docAgnosticFormat); - return ( -
- - - {_.isUndefined(this.state.docAgnosticFormat) ? -
-
-
- -
-
Loading documentation...
-
-
: -
-
-
- -
-
-
-
-
-

- - {docsInfo.packageName} - -

- {this.renderDocumentation()} -
-
-
- } -
- ); - } - private renderDocumentation(): React.ReactNode { - const typeDocSection = this.state.docAgnosticFormat[docsInfo.sections.types]; - const typeDefinitionByName = _.keyBy(typeDocSection.types, 'name'); - - const subMenus = _.values(docsInfo.getMenu()); - const orderedSectionNames = _.flatten(subMenus); - const sections = _.map(orderedSectionNames, this.renderSection.bind(this, typeDefinitionByName)); - - return sections; - } - private renderSection(typeDefinitionByName: TypeDefinitionByName, sectionName: string): React.ReactNode { - const docSection = this.state.docAgnosticFormat[sectionName]; - - const markdownFileIfExists = docsInfo.sectionNameToMarkdown[sectionName]; - if (!_.isUndefined(markdownFileIfExists)) { - return ( - - ); - } - - if (_.isUndefined(docSection)) { - return null; - } - - const typeDefs = _.map(docSection.types, customType => { - return ( - - ); - }); - const propertyDefs = _.map(docSection.properties, this.renderProperty.bind(this)); - const methodDefs = _.map(docSection.methods, method => { - const isConstructor = false; - return this.renderMethodBlocks(method, sectionName, isConstructor, typeDefinitionByName); - }); - return ( -
- - - {sectionName === docsInfo.sections.zeroEx && docSection.constructors.length > 0 && -
-

Constructor

- {this.renderZeroExConstructors(docSection.constructors, typeDefinitionByName)} -
- } - {docSection.properties.length > 0 && -
-

Properties

-
{propertyDefs}
-
- } - {docSection.methods.length > 0 && -
-

Methods

-
{methodDefs}
-
- } - {typeDefs.length > 0 && -
-
{typeDefs}
-
- } -
- ); - } - private renderZeroExConstructors(constructors: TypescriptMethod[], - typeDefinitionByName: TypeDefinitionByName): React.ReactNode { - const constructorDefs = _.map(constructors, constructor => { - return this.renderMethodBlocks( - constructor, docsInfo.sections.zeroEx, constructor.isConstructor, typeDefinitionByName, - ); - }); - return ( -
- {constructorDefs} -
- ); - } - private renderProperty(property: Property): React.ReactNode { - return ( -
- - {property.name}: - - - {property.comment && - - } -
- ); - } - private renderMethodBlocks(method: TypescriptMethod, sectionName: string, isConstructor: boolean, - typeDefinitionByName: TypeDefinitionByName): React.ReactNode { - return ( - - ); - } - private scrollToHash(): void { - const hashWithPrefix = this.props.location.hash; - let hash = hashWithPrefix.slice(1); - if (_.isEmpty(hash)) { - hash = SCROLL_TOP_ID; // scroll to the top - } - - scroller.scrollTo(hash, {duration: 0, offset: 0, containerId: 'documentation'}); - } - private async fetchJSONDocsFireAndForgetAsync(preferredVersionIfExists?: string): Promise { - const versionToFileName = await docUtils.getVersionToFileNameAsync(docsInfo.docsJsonRoot); - const versions = _.keys(versionToFileName); - this.props.dispatcher.updateAvailableDocVersions(versions); - const sortedVersions = semverSort.desc(versions); - const latestVersion = sortedVersions[0]; - - let versionToFetch = latestVersion; - if (!_.isUndefined(preferredVersionIfExists)) { - const preferredVersionFileNameIfExists = versionToFileName[preferredVersionIfExists]; - if (!_.isUndefined(preferredVersionFileNameIfExists)) { - versionToFetch = preferredVersionIfExists; - } - } - this.props.dispatcher.updateCurrentDocsVersion(versionToFetch); - - const versionFileNameToFetch = versionToFileName[versionToFetch]; - const versionDocObj = await docUtils.getJSONDocFileAsync( - versionFileNameToFetch, docsInfo.docsJsonRoot, - ); - const docAgnosticFormat = typeDocUtils.convertToDocAgnosticFormat( - docsInfo, (versionDocObj as TypeDocNode), - ); - - this.setState({ - docAgnosticFormat, - }, () => { - this.scrollToHash(); - }); - } -} -- cgit v1.2.3