From f4a2e227e1a7224fbbe9c99d9aa033d176a9c4de Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Sun, 29 Jul 2018 21:58:39 +0200 Subject: Remove all in-package monorepo-scripts by adding doc gen/upload and aggregate release note publishing to publish script --- packages/react-docs/src/monorepo_scripts/postpublish.ts | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 packages/react-docs/src/monorepo_scripts/postpublish.ts (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/monorepo_scripts/postpublish.ts b/packages/react-docs/src/monorepo_scripts/postpublish.ts deleted file mode 100644 index dcb99d0f7..000000000 --- a/packages/react-docs/src/monorepo_scripts/postpublish.ts +++ /dev/null @@ -1,8 +0,0 @@ -import { postpublishUtils } from '@0xproject/monorepo-scripts'; - -import * as packageJSON from '../package.json'; -import * as tsConfigJSON from '../tsconfig.json'; - -const cwd = `${__dirname}/..`; -// tslint:disable-next-line:no-floating-promises -postpublishUtils.runAsync(packageJSON, tsConfigJSON, cwd); -- cgit v1.2.3 From 11869122b4fe00c834347f9911985d7b2572bc9b Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Wed, 1 Aug 2018 17:33:28 +0200 Subject: Update React-scroll, getting rid of the need to manually set the url hash --- packages/react-docs/src/components/signature.tsx | 2 +- packages/react-docs/src/components/type.tsx | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index 77e9cc909..5f28050d2 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -27,7 +27,7 @@ const defaultProps = { }; export const Signature: React.SFC = (props: SignatureProps) => { - const sectionName = constants.TYPES_SECTION_NAME; + const sectionName = props.sectionName; const parameters = renderParameters(props.parameters, props.docsInfo, sectionName, props.typeDefinitionByName); const paramStringArray: any[] = []; // HACK: For now we don't put params on newlines if there are less then 2 of them. diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index e453349ef..04fcd9998 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -182,6 +182,7 @@ export function Type(props: TypeProps): any { -- cgit v1.2.3 From 3bdf6004ca74dd9eb380aa61cf9e69c47725116a Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Wed, 1 Aug 2018 17:36:37 +0200 Subject: Start refactoring docs to remove unnecessary configs given more concise TypeDoc JSON --- .../react-docs/src/components/documentation.tsx | 44 +++---- .../react-docs/src/components/property_block.tsx | 70 +++++++++++ packages/react-docs/src/components/type.tsx | 29 ++--- .../react-docs/src/components/type_definition.tsx | 3 - packages/react-docs/src/docs_info.ts | 56 +++------ packages/react-docs/src/index.ts | 10 +- packages/react-docs/src/types.ts | 19 ++- packages/react-docs/src/utils/typedoc_utils.ts | 135 +++++++++++---------- 8 files changed, 206 insertions(+), 160 deletions(-) create mode 100644 packages/react-docs/src/components/property_block.tsx (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index ff33220d2..4f776b237 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -1,7 +1,9 @@ import { + AnchorTitle, colors, constants as sharedConstants, EtherscanLinkSuffixes, + HeaderSizes, MarkdownSection, NestedSidebarMenu, Networks, @@ -32,8 +34,7 @@ import { Badge } from './badge'; import { Comment } from './comment'; import { EventDefinition } from './event_definition'; import { SignatureBlock } from './signature_block'; -import { SourceLink } from './source_link'; -import { Type } from './type'; +import { PropertyBlock } from './property_block'; import { TypeDefinition } from './type_definition'; const networkNameToColor: { [network: string]: string } = { @@ -129,7 +130,7 @@ export class Documentation extends React.Component @@ -172,7 +173,7 @@ export class Documentation extends React.Component {docSection.comment && } - {!_.isEmpty(docSection.constructors) && - this.props.docsInfo.isVisibleConstructor(sectionName) && ( -
-

Constructor

- {this._renderConstructors(docSection.constructors, sectionName, typeDefinitionByName)} -
- )} + {!_.isEmpty(docSection.constructors) && ( +
+

Constructor

+ {this._renderConstructors(docSection.constructors, sectionName, typeDefinitionByName)} +
+ )} {!_.isEmpty(docSection.properties) && (

Properties

@@ -345,20 +345,14 @@ export class Documentation extends React.Component - - {property.name}:{' '} - - - {property.source && ( - - )} - {property.comment && } -
+ ); } private _renderSignatureBlocks( diff --git a/packages/react-docs/src/components/property_block.tsx b/packages/react-docs/src/components/property_block.tsx new file mode 100644 index 000000000..6e7f90c6c --- /dev/null +++ b/packages/react-docs/src/components/property_block.tsx @@ -0,0 +1,70 @@ +import { AnchorTitle, HeaderSizes } from '@0xproject/react-shared'; +import * as React from 'react'; + +import { DocsInfo } from '../docs_info'; +import { Property } from '../types'; +import { constants } from '../utils/constants'; + +import { Comment } from './comment'; +import { Type } from './type'; +import { SourceLink } from './source_link'; + +export interface PropertyBlockProps { + property: Property; + sectionName: string; + docsInfo: DocsInfo; + sourceUrl: string; + selectedVersion: string; +} + +export interface PropertyBlockState { + shouldShowAnchor: boolean; +} + +export class PropertyBlock extends React.Component { + constructor(props: PropertyBlockProps) { + super(props); + this.state = { + shouldShowAnchor: false, + }; + } + public render(): React.ReactNode { + const property = this.props.property; + const sectionName = this.props.sectionName; + return ( +
+
+ +
+ + {property.name}:{' '} + + + {property.source && ( + + )} + {property.comment && } +
+ ); + } + private _setAnchorVisibility(shouldShowAnchor: boolean): void { + this.setState({ + shouldShowAnchor, + }); + } +} diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 04fcd9998..3504be303 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -9,6 +9,7 @@ import { DocsInfo } from '../docs_info'; import { Type as TypeDef, TypeDefinitionByName, TypeDocTypes } from '../types'; import { Signature } from './signature'; +import { constants } from '../utils/constants'; import { TypeDefinition } from './type_definition'; export interface TypeProps { @@ -43,7 +44,7 @@ export function Type(props: TypeProps): any { - {_.isUndefined(typeDefinition) || sharedUtils.isUserOnMobile() ? ( - - {typeName} - + {sharedUtils.isUserOnMobile() ? ( + {typeName} ) : ( { - const versionIntroducedIfExists = this._docsInfo.menuSubsectionToVersionWhenIntroduced[contractName]; - if (!_.isUndefined(versionIntroducedIfExists)) { - const doesExistInSelectedVersion = compareVersions(selectedVersion, versionIntroducedIfExists) >= 0; - return doesExistInSelectedVersion; - } else { - return true; - } - }); - return finalMenu; + return this._docsInfo.menu; } public getMenuSubsectionsBySection(docAgnosticFormat?: DocAgnosticFormat): MenuSubsectionsBySection { const menuSubsectionsBySection = {} as MenuSubsectionsBySection; @@ -96,12 +67,18 @@ export class DocsInfo { 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]; + const propertiesSortedByName = _.sortBy(docSection.properties, 'name'); + const propertyNames = _.map(propertiesSortedByName, m => m.name); + const methodsSortedByName = _.sortBy(docSection.methods, 'name'); + const methodNames = _.map(methodsSortedByName, m => m.name); const sortedFunctionNames = _.sortBy(docSection.functions, 'name'); const functionNames = _.map(sortedFunctionNames, m => m.name); - menuSubsectionsBySection[sectionName] = [...eventNames, ...functionNames, ...methodNames]; + menuSubsectionsBySection[sectionName] = [ + ...eventNames, + ...propertyNames, + ...functionNames, + ...methodNames, + ]; } }); return menuSubsectionsBySection; @@ -115,14 +92,11 @@ export class DocsInfo { const typeDefinitionByName = _.keyBy(typeDocSection.types, 'name') as any; return typeDefinitionByName; } - public isVisibleConstructor(sectionName: string): boolean { - return _.includes(this._docsInfo.visibleConstructors, sectionName); - } - public convertToDocAgnosticFormat(docObj: DoxityDocObj | TypeDocNode): DocAgnosticFormat { + public convertToDocAgnosticFormat(docObj: DoxityDocObj | GeneratedDocJson): DocAgnosticFormat { if (this.type === SupportedDocJson.Doxity) { return doxityUtils.convertToDocAgnosticFormat(docObj as DoxityDocObj); } else { - return typeDocUtils.convertToDocAgnosticFormat(docObj as TypeDocNode, this); + return typeDocUtils.convertToDocAgnosticFormat(docObj as GeneratedDocJson, this); } } } diff --git a/packages/react-docs/src/index.ts b/packages/react-docs/src/index.ts index 30f5011b7..e4424f679 100644 --- a/packages/react-docs/src/index.ts +++ b/packages/react-docs/src/index.ts @@ -15,6 +15,14 @@ export { Type } from './components/type'; export { DocsInfo } from './docs_info'; -export { DocsInfoConfig, DocAgnosticFormat, DoxityDocObj, DocsMenu, SupportedDocJson, TypeDocNode } from './types'; +export { + DocsInfoConfig, + DocAgnosticFormat, + DoxityDocObj, + DocsMenu, + SupportedDocJson, + TypeDocNode, + GeneratedDocJson, +} from './types'; export { constants } from './utils/constants'; diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index cbc774c2e..83ad157d1 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -10,18 +10,13 @@ export interface DocsInfoConfig { menu: DocsMenu; sections: SectionsMap; sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion; - visibleConstructors: string[]; - sectionNameToModulePath?: { [sectionName: string]: string[] }; - menuSubsectionToVersionWhenIntroduced?: { [sectionName: string]: string }; contractsByVersionByNetworkId?: ContractsByVersionByNetworkId; typeConfigs?: DocsInfoTypeConfigs; } export interface DocsInfoTypeConfigs { typeNameToExternalLink?: { [typeName: string]: string }; - publicTypes?: string[]; typeNameToPrefix?: { [typeName: string]: string }; - typeNameToDocSection?: { [typeName: string]: string }; } export interface DocsMenu { @@ -292,3 +287,17 @@ export enum AbiTypes { Function = 'function', Event = 'event', } + +export interface ExportNameToTypedocName { + [exportName: string]: string; +} + +export interface Metadata { + exportPathToTypedocName: ExportNameToTypedocName; + exportPathOrder: string[]; +} + +export interface GeneratedDocJson { + metadata: Metadata; + typedocJson: TypeDocNode; +} diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index a6d938e94..1e7c29ce8 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -19,8 +19,11 @@ import { TypeParameter, TypescriptFunction, TypescriptMethod, + GeneratedDocJson, } from '../types'; +import { constants } from './constants'; + export const typeDocUtils = { isType(entity: TypeDocNode): boolean { return ( @@ -55,62 +58,68 @@ export const typeDocUtils = { }); return moduleDefinitions; }, - convertToDocAgnosticFormat(typeDocJson: TypeDocNode, docsInfo: DocsInfo): DocAgnosticFormat { - const subMenus = _.values(docsInfo.getMenu()); - const orderedSectionNames = _.flatten(subMenus); + convertToDocAgnosticFormat(generatedDocJson: GeneratedDocJson, docsInfo: DocsInfo): DocAgnosticFormat { + const exportPathOrder = generatedDocJson.metadata.exportPathOrder; + const exportPathToTypedocName = generatedDocJson.metadata.exportPathToTypedocName; + const typeDocJson = generatedDocJson.typedocJson; + + const typeDocNameOrder = _.map(exportPathOrder, exportPath => { + return exportPathToTypedocName[exportPath]; + }); + const docAgnosticFormat: DocAgnosticFormat = {}; - _.each(orderedSectionNames, sectionName => { - const modulePathsIfExists = docsInfo.getModulePathsIfExists(sectionName); - if (_.isUndefined(modulePathsIfExists)) { - return; // no-op - } - const packageDefinitions = typeDocUtils.getModuleDefinitionsBySectionName(typeDocJson, modulePathsIfExists); - let packageDefinitionWithMergedChildren; - if (_.isEmpty(packageDefinitions)) { - return; // no-op - } else if (packageDefinitions.length === 1) { - packageDefinitionWithMergedChildren = packageDefinitions[0]; - } else { - // HACK: For now, if there are two modules to display in a single section, - // we simply concat the children. This works for our limited use-case where - // we want to display types stored in two files under a single section - packageDefinitionWithMergedChildren = packageDefinitions[0]; - for (let i = 1; i < packageDefinitions.length; i++) { - packageDefinitionWithMergedChildren.children = [ - ...packageDefinitionWithMergedChildren.children, - ...packageDefinitions[i].children, - ]; + const typeEntities: TypeDocNode[] = []; + _.each(typeDocNameOrder, typeDocName => { + const fileChildIndex = _.findIndex(typeDocJson.children, child => child.name === typeDocName); + const fileChild = typeDocJson.children[fileChildIndex]; + let sectionName: string; + _.each(fileChild.children, (child, j) => { + switch (child.kindString) { + case KindString.Class: + case KindString.ObjectLiteral: { + sectionName = child.name; + docsInfo.sections[sectionName] = sectionName; + docsInfo.menu[sectionName] = [sectionName]; + const entities = child.children; + const commentObj = child.comment; + const sectionComment = !_.isUndefined(commentObj) ? commentObj.shortText : ''; + const docSection = typeDocUtils._convertEntitiesToDocSection(entities, docsInfo, sectionName); + docSection.comment = sectionComment; + docAgnosticFormat[sectionName] = docSection; + break; + } + case KindString.Function: { + sectionName = child.name; + docsInfo.sections[sectionName] = sectionName; + docsInfo.menu[sectionName] = [sectionName]; + const entities = [child]; + const commentObj = child.comment; + const SectionComment = !_.isUndefined(commentObj) ? commentObj.shortText : ''; + const docSection = typeDocUtils._convertEntitiesToDocSection(entities, docsInfo, sectionName); + docSection.comment = SectionComment; + docAgnosticFormat[sectionName] = docSection; + break; + } + case KindString.Interface: + case KindString.Variable: + case KindString.Enumeration: + case KindString.TypeAlias: + typeEntities.push(child); + break; + default: + throw errorUtils.spawnSwitchErr('kindString', child.kindString); } - } - - let entities; - let packageComment = ''; - // HACK: We assume 1 exported class per file - const classChildren = _.filter(packageDefinitionWithMergedChildren.children, (child: TypeDocNode) => { - return child.kindString === KindString.Class; }); - if (classChildren.length > 1 && sectionName !== 'types') { - throw new Error('`react-docs` only supports projects with 1 exported class per file'); - } - const isClassExport = packageDefinitionWithMergedChildren.children[0].kindString === KindString.Class; - const isObjectLiteralExport = - packageDefinitionWithMergedChildren.children[0].kindString === KindString.ObjectLiteral; - if (isClassExport) { - entities = packageDefinitionWithMergedChildren.children[0].children; - const commentObj = packageDefinitionWithMergedChildren.children[0].comment; - packageComment = !_.isUndefined(commentObj) ? commentObj.shortText : packageComment; - } else if (isObjectLiteralExport) { - entities = packageDefinitionWithMergedChildren.children[0].children; - const commentObj = packageDefinitionWithMergedChildren.children[0].comment; - packageComment = !_.isUndefined(commentObj) ? commentObj.shortText : packageComment; - } else { - entities = packageDefinitionWithMergedChildren.children; - } - - const docSection = typeDocUtils._convertEntitiesToDocSection(entities, docsInfo, sectionName); - docSection.comment = packageComment; - docAgnosticFormat[sectionName] = docSection; }); + docsInfo.sections[constants.TYPES_SECTION_NAME] = constants.TYPES_SECTION_NAME; + docsInfo.menu[constants.TYPES_SECTION_NAME] = [constants.TYPES_SECTION_NAME]; + const docSection = typeDocUtils._convertEntitiesToDocSection( + typeEntities, + docsInfo, + constants.TYPES_SECTION_NAME, + ); + docAgnosticFormat[constants.TYPES_SECTION_NAME] = docSection; + return docAgnosticFormat; }, _convertEntitiesToDocSection(entities: TypeDocNode[], docsInfo: DocsInfo, sectionName: string): DocSection { @@ -175,18 +184,16 @@ export const typeDocUtils = { case KindString.Variable: case KindString.Enumeration: case KindString.TypeAlias: - if (docsInfo.isPublicType(entity.name)) { - const customType = typeDocUtils._convertCustomType( - entity, - docsInfo.sections, - sectionName, - docsInfo.id, - ); - const seenTypeNames = _.map(docSection.types, t => t.name); - const isUnseen = !_.includes(seenTypeNames, customType.name); - if (isUnseen) { - docSection.types.push(customType); - } + const customType = typeDocUtils._convertCustomType( + entity, + docsInfo.sections, + sectionName, + docsInfo.id, + ); + const seenTypeNames = _.map(docSection.types, t => t.name); + const isUnseen = !_.includes(seenTypeNames, customType.name); + if (isUnseen) { + docSection.types.push(customType); } break; -- cgit v1.2.3 From 32e1c2ac970069f5251bd3cd7a31072f0547cf2c Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Wed, 1 Aug 2018 19:02:20 +0200 Subject: Add padding above anchor titles so they show up nice when scrolled to --- packages/react-docs/src/components/property_block.tsx | 2 +- packages/react-docs/src/components/type_definition.tsx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/property_block.tsx b/packages/react-docs/src/components/property_block.tsx index 6e7f90c6c..466082a91 100644 --- a/packages/react-docs/src/components/property_block.tsx +++ b/packages/react-docs/src/components/property_block.tsx @@ -34,7 +34,7 @@ export class PropertyBlock extends React.Component Date: Wed, 1 Aug 2018 20:48:19 +0200 Subject: Add callpath to properties --- .../react-docs/src/components/property_block.tsx | 2 +- packages/react-docs/src/types.ts | 1 + packages/react-docs/src/utils/typedoc_utils.ts | 39 +++++++++++++--------- 3 files changed, 25 insertions(+), 17 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/property_block.tsx b/packages/react-docs/src/components/property_block.tsx index 466082a91..074c59c5f 100644 --- a/packages/react-docs/src/components/property_block.tsx +++ b/packages/react-docs/src/components/property_block.tsx @@ -48,7 +48,7 @@ export class PropertyBlock extends React.Component - {property.name}:{' '} + {(property as any).callPath}{property.name}:{' '} {property.source && ( diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index 83ad157d1..ca869df1c 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -202,6 +202,7 @@ export interface Property { type: Type; source?: Source; comment?: string; + callPath?: string; } export interface BaseMethod { diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 1e7c29ce8..1c685f915 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -283,6 +283,9 @@ export const typeDocUtils = { _convertProperty(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): Property { const source = entity.sources[0]; const commentIfExists = !_.isUndefined(entity.comment) ? entity.comment.shortText : undefined; + const isConstructor = false; + const isStatic = _.isUndefined(entity.flags.isStatic) ? false : entity.flags.isStatic; + const callPath = typeDocUtils._getCallPath(sectionName, sections, isStatic, isConstructor, docId, entity.name); const property = { name: entity.name, type: typeDocUtils._convertType(entity.type, sections, sectionName, docId), @@ -291,6 +294,7 @@ export const typeDocUtils = { line: source.line, }, comment: commentIfExists, + callPath, }; return property; }, @@ -306,22 +310,6 @@ export const typeDocUtils = { const hasComment = !_.isUndefined(signature.comment); const isStatic = _.isUndefined(entity.flags.isStatic) ? false : entity.flags.isStatic; - // HACK: we use the fact that the sectionName is the same as the property name at the top-level - // of the public interface. In the future, we shouldn't use this hack but rather get it from the JSON. - let callPath; - if (isConstructor || entity.name === '__type') { - callPath = ''; - // TODO: Get rid of this 0x-specific logic - } else if (docId === 'ZERO_EX_JS') { - const topLevelInterface = isStatic ? 'ZeroEx.' : 'zeroEx.'; - callPath = - !_.isUndefined(sections.zeroEx) && sectionName !== sections.zeroEx - ? `${topLevelInterface}${sectionName}.` - : topLevelInterface; - } else { - callPath = `${sectionName}.`; - } - const parameters = _.map(signature.parameters, param => { return typeDocUtils._convertParameter(param, sections, sectionName, docId); }); @@ -330,6 +318,7 @@ export const typeDocUtils = { ? undefined : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId); + const callPath = typeDocUtils._getCallPath(sectionName, sections, isStatic, isConstructor, docId, entity.name); const method = { isConstructor, isStatic, @@ -347,6 +336,24 @@ export const typeDocUtils = { }; return method; }, + _getCallPath(sectionName: string, sections: SectionsMap, isStatic: boolean, isConstructor: boolean, docId: string, entityName: string) { + // HACK: we use the fact that the sectionName is the same as the property name at the top-level + // of the public interface. In the future, we shouldn't use this hack but rather get it from the JSON. + let callPath; + if (isConstructor || entityName === '__type') { + callPath = ''; + // TODO: Get rid of this 0x-specific logic + } else if (docId === 'ZERO_EX_JS') { + const topLevelInterface = isStatic ? 'ZeroEx.' : 'zeroEx.'; + callPath = + !_.isUndefined(sections.zeroEx) && sectionName !== sections.zeroEx + ? `${topLevelInterface}${sectionName}.` + : topLevelInterface; + } else { + callPath = `${sectionName}.`; + } + return callPath; + }, _convertFunction( entity: TypeDocNode, sections: SectionsMap, -- cgit v1.2.3 From 2494af99aad4dd58c0d4e647dedf72946cb3c20b Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Wed, 1 Aug 2018 21:00:45 +0200 Subject: Prefix menu and sections with markdown as that is all the should now be defined --- packages/react-docs/src/docs_info.ts | 9 ++------- packages/react-docs/src/types.ts | 4 ++-- 2 files changed, 4 insertions(+), 9 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index dd3cb9a96..0637f3e65 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -28,21 +28,16 @@ export class DocsInfo { public sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion; public contractsByVersionByNetworkId?: ContractsByVersionByNetworkId; public typeConfigs: DocsInfoTypeConfigs; - private readonly _docsInfo: DocsInfoConfig; constructor(config: DocsInfoConfig) { this.id = config.id; this.type = config.type; - this.menu = config.menu; + this.menu = config.markdownMenu; this.displayName = config.displayName; this.packageUrl = config.packageUrl; - this.sections = config.sections; + this.sections = config.markdownSections; this.sectionNameToMarkdownByVersion = config.sectionNameToMarkdownByVersion; this.contractsByVersionByNetworkId = config.contractsByVersionByNetworkId; this.typeConfigs = config.typeConfigs; - this._docsInfo = config; - } - public getMenu(selectedVersion?: string): { [section: string]: string[] } { - return this._docsInfo.menu; } public getMenuSubsectionsBySection(docAgnosticFormat?: DocAgnosticFormat): MenuSubsectionsBySection { const menuSubsectionsBySection = {} as MenuSubsectionsBySection; diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index ca869df1c..aebd823db 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -7,8 +7,8 @@ export interface DocsInfoConfig { type: SupportedDocJson; displayName: string; packageUrl: string; - menu: DocsMenu; - sections: SectionsMap; + markdownMenu: DocsMenu; + markdownSections: SectionsMap; sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion; contractsByVersionByNetworkId?: ContractsByVersionByNetworkId; typeConfigs?: DocsInfoTypeConfigs; -- cgit v1.2.3 From b3473ff89f4d276fe74dd8e62680ab975fe24639 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 2 Aug 2018 17:27:10 +0200 Subject: Remove unused var --- packages/react-docs/src/utils/typedoc_utils.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 1c685f915..e2b259b13 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -73,7 +73,7 @@ export const typeDocUtils = { const fileChildIndex = _.findIndex(typeDocJson.children, child => child.name === typeDocName); const fileChild = typeDocJson.children[fileChildIndex]; let sectionName: string; - _.each(fileChild.children, (child, j) => { + _.each(fileChild.children, child => { switch (child.kindString) { case KindString.Class: case KindString.ObjectLiteral: { -- cgit v1.2.3 From 9a3b630b1989abbe1d6784f121fd0a60169e3012 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 2 Aug 2018 17:27:29 +0200 Subject: prettier --- packages/react-docs/src/utils/typedoc_utils.ts | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index e2b259b13..35d28627f 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -336,7 +336,14 @@ export const typeDocUtils = { }; return method; }, - _getCallPath(sectionName: string, sections: SectionsMap, isStatic: boolean, isConstructor: boolean, docId: string, entityName: string) { + _getCallPath( + sectionName: string, + sections: SectionsMap, + isStatic: boolean, + isConstructor: boolean, + docId: string, + entityName: string, + ) { // HACK: we use the fact that the sectionName is the same as the property name at the top-level // of the public interface. In the future, we shouldn't use this hack but rather get it from the JSON. let callPath; -- cgit v1.2.3 From 90ead59d34bf5218cf4e1e5317a4ffeb497da8e1 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 2 Aug 2018 21:09:18 +0200 Subject: Add support for rendering nested IndexSignatures --- packages/react-docs/src/components/interface.tsx | 8 ++-- packages/react-docs/src/components/signature.tsx | 1 - packages/react-docs/src/components/type.tsx | 45 ++++++++++++++------ packages/react-docs/src/types.ts | 4 +- packages/react-docs/src/utils/typedoc_utils.ts | 53 ++++++++++++++---------- 5 files changed, 71 insertions(+), 40 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/interface.tsx b/packages/react-docs/src/components/interface.tsx index a881c7fec..915b4bbc6 100644 --- a/packages/react-docs/src/components/interface.tsx +++ b/packages/react-docs/src/components/interface.tsx @@ -2,7 +2,7 @@ import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { CustomType, TypeDocTypes } from '../types'; +import { CustomType } from '../types'; import { Signature } from './signature'; import { Type } from './type'; @@ -19,9 +19,7 @@ export const Interface = (props: InterfaceProps) => { return ( {property.name}:{' '} - {property.type && property.type.typeDocType !== TypeDocTypes.Reflection ? ( - - ) : ( + {property.type && !_.isUndefined(property.type.method) ? ( { shouldUseArrowSyntax={true} docsInfo={props.docsInfo} /> + ) : ( + )}, ); diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index 5f28050d2..d9567c9f6 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -3,7 +3,6 @@ import * as React from 'react'; import { DocsInfo } from '../docs_info'; import { Parameter, Type as TypeDef, TypeDefinitionByName, TypeParameter } from '../types'; -import { constants } from '../utils/constants'; import { Type } from './type'; diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 3504be303..ea66c7b1e 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -93,19 +93,38 @@ export function Type(props: TypeProps): any { break; case TypeDocTypes.Reflection: - typeName = ( - - ); + if (!_.isUndefined(type.method)) { + typeName = ( + + ); + } else if (!_.isUndefined(type.indexSignature)) { + const is = type.indexSignature; + const param = ( + + {is.keyName}:{' '} + + + ); + typeName = ( + + {'{'}[{param}]: {is.valueName} + {'}'} + + ); + } else { + throw new Error(`Unrecognized Reflection type that isn't a Method nor an Index Signature`); + } + break; case TypeDocTypes.TypeParameter: diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index aebd823db..79dfe9f4f 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -35,6 +35,7 @@ export interface TypeDocType { typeArguments?: TypeDocType[]; declaration: TypeDocNode; elementType?: TypeDocType; + indexSignature?: TypeDocNode; } export interface TypeDocFlags { @@ -64,7 +65,7 @@ export interface TypeDocNode { returns?: string; declaration: TypeDocNode; flags?: TypeDocFlags; - indexSignature?: TypeDocNode | TypeDocNode[]; // TypeDocNode in TypeDoc V0.9.0 + indexSignature?: TypeDocNode; signatures?: TypeDocNode[]; parameters?: TypeDocNode[]; typeParameter?: TypeDocNode[]; @@ -156,6 +157,7 @@ export interface Type { elementType?: ElementType; types?: Type[]; method?: TypescriptMethod; + indexSignature?: IndexSignature; } export interface ElementType { diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 35d28627f..f1f42c36d 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -63,9 +63,12 @@ export const typeDocUtils = { const exportPathToTypedocName = generatedDocJson.metadata.exportPathToTypedocName; const typeDocJson = generatedDocJson.typedocJson; - const typeDocNameOrder = _.map(exportPathOrder, exportPath => { - return exportPathToTypedocName[exportPath]; - }); + // TODO: Extract the non typeDoc exports, and render them somehow + const typeDocNameOrder = _.compact( + _.map(exportPathOrder, exportPath => { + return exportPathToTypedocName[exportPath]; + }), + ); const docAgnosticFormat: DocAgnosticFormat = {}; const typeEntities: TypeDocNode[] = []; @@ -111,14 +114,16 @@ export const typeDocUtils = { } }); }); - docsInfo.sections[constants.TYPES_SECTION_NAME] = constants.TYPES_SECTION_NAME; - docsInfo.menu[constants.TYPES_SECTION_NAME] = [constants.TYPES_SECTION_NAME]; - const docSection = typeDocUtils._convertEntitiesToDocSection( - typeEntities, - docsInfo, - constants.TYPES_SECTION_NAME, - ); - docAgnosticFormat[constants.TYPES_SECTION_NAME] = docSection; + if (!_.isEmpty(typeEntities)) { + docsInfo.sections[constants.TYPES_SECTION_NAME] = constants.TYPES_SECTION_NAME; + docsInfo.menu[constants.TYPES_SECTION_NAME] = [constants.TYPES_SECTION_NAME]; + const docSection = typeDocUtils._convertEntitiesToDocSection( + typeEntities, + docsInfo, + constants.TYPES_SECTION_NAME, + ); + docAgnosticFormat[constants.TYPES_SECTION_NAME] = docSection; + } return docAgnosticFormat; }, @@ -218,13 +223,7 @@ export const typeDocUtils = { ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId) : undefined; const doesIndexSignatureExist = !_.isUndefined(entity.indexSignature); - const isIndexSignatureArray = _.isArray(entity.indexSignature); - // HACK: TypeDoc Versions <0.9.0 indexSignature is of type TypeDocNode[] - // Versions >0.9.0 have it as type TypeDocNode - const indexSignature = - doesIndexSignatureExist && isIndexSignatureArray - ? (entity.indexSignature as TypeDocNode[])[0] - : (entity.indexSignature as TypeDocNode); + const indexSignature = entity.indexSignature as TypeDocNode; const indexSignatureIfExists = doesIndexSignatureExist ? typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId) : undefined; @@ -305,6 +304,9 @@ export const typeDocUtils = { sectionName: string, docId: string, ): TypescriptMethod { + if (_.isUndefined(entity.signatures)) { + console.log(entity); + } const signature = entity.signatures[0]; const source = entity.sources[0]; const hasComment = !_.isUndefined(signature.comment); @@ -436,9 +438,17 @@ export const typeDocUtils = { }); const isConstructor = false; - const methodIfExists = !_.isUndefined(entity.declaration) - ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId) - : undefined; + const doesIndexSignatureExist = + !_.isUndefined(entity.declaration) && !_.isUndefined(entity.declaration.indexSignature); + let indexSignatureIfExists; + if (doesIndexSignatureExist) { + const indexSignature = entity.declaration.indexSignature as TypeDocNode; + indexSignatureIfExists = typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId); + } + const methodIfExists = + !_.isUndefined(entity.declaration) && !doesIndexSignatureExist + ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId) + : undefined; const elementTypeIfExists = !_.isUndefined(entity.elementType) ? { @@ -455,6 +465,7 @@ export const typeDocUtils = { elementType: elementTypeIfExists, types, method: methodIfExists, + indexSignature: indexSignatureIfExists, }; return type; }, -- cgit v1.2.3 From 4a2a22a43b5d904834cddae5768d9adf3efedf30 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 3 Aug 2018 11:44:50 +0200 Subject: Refactor logic for clarity --- packages/react-docs/src/utils/typedoc_utils.ts | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index f1f42c36d..ad794c0fa 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -437,18 +437,23 @@ export const typeDocUtils = { return typeDocUtils._convertType(t, sections, sectionName, docId); }); - const isConstructor = false; + let indexSignatureIfExists; + let methodIfExists; const doesIndexSignatureExist = !_.isUndefined(entity.declaration) && !_.isUndefined(entity.declaration.indexSignature); - let indexSignatureIfExists; if (doesIndexSignatureExist) { const indexSignature = entity.declaration.indexSignature as TypeDocNode; indexSignatureIfExists = typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId); + } else if (!_.isUndefined(entity.declaration)) { + const isConstructor = false; + methodIfExists = typeDocUtils._convertMethod( + entity.declaration, + isConstructor, + sections, + sectionName, + docId, + ); } - const methodIfExists = - !_.isUndefined(entity.declaration) && !doesIndexSignatureExist - ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId) - : undefined; const elementTypeIfExists = !_.isUndefined(entity.elementType) ? { -- cgit v1.2.3 From d136df7679b85eff054178ae8103ecd1f3b324f9 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 3 Aug 2018 13:02:14 +0200 Subject: Color-code basic type arrays orange aswell --- packages/react-docs/src/components/type.tsx | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index ea66c7b1e..40564c0d6 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -12,6 +12,8 @@ import { Signature } from './signature'; import { constants } from '../utils/constants'; import { TypeDefinition } from './type_definition'; +const basicJsTypes = ['string', 'number', 'undefined', 'null', 'boolean']; + export interface TypeProps { type: TypeDef; docsInfo: DocsInfo; @@ -73,6 +75,9 @@ export function Type(props: TypeProps): any { case TypeDocTypes.Array: typeName = type.elementType.name; + if (_.includes(basicJsTypes, typeName)) { + typeNameColor = colors.orange; + } break; case TypeDocTypes.Union: -- cgit v1.2.3 From b8c8258404fa7959b71dd9e87fba16d32b57a868 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 3 Aug 2018 17:13:38 +0200 Subject: Don't render object literal properties that start with underscore since are private --- packages/react-docs/src/components/property_block.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/property_block.tsx b/packages/react-docs/src/components/property_block.tsx index 074c59c5f..ea80ba7b7 100644 --- a/packages/react-docs/src/components/property_block.tsx +++ b/packages/react-docs/src/components/property_block.tsx @@ -48,7 +48,8 @@ export class PropertyBlock extends React.Component - {(property as any).callPath}{property.name}:{' '} + {(property as any).callPath} + {property.name}:{' '} {property.source && ( -- cgit v1.2.3 From 0d3d9dad846d01e84be3b52d48bfabd9e1853b66 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 3 Aug 2018 17:14:14 +0200 Subject: Don't process functions beginning with underscores --- packages/react-docs/src/utils/typedoc_utils.ts | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index ad794c0fa..b74b9562b 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -154,8 +154,17 @@ export const typeDocUtils = { case KindString.Function: if (entity.flags.isExported) { - const func = typeDocUtils._convertFunction(entity, docsInfo.sections, sectionName, docsInfo.id); - docSection.functions.push(func); + const funcName = (entity as TypeDocNode).signatures[0].name; + const isPublicFunc = !_.startsWith(funcName, '_'); + if (isPublicFunc) { + const func = typeDocUtils._convertFunction( + entity, + docsInfo.sections, + sectionName, + docsInfo.id, + ); + docSection.functions.push(func); + } } break; -- cgit v1.2.3 From c17d6c47c3253cf32c2dada8f7f871563f7209e9 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 3 Aug 2018 19:24:58 +0200 Subject: Properly render class/objectLiteral properties that are simple variables --- packages/react-docs/src/utils/typedoc_utils.ts | 42 ++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index b74b9562b..2eee2fa59 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -86,7 +86,13 @@ export const typeDocUtils = { const entities = child.children; const commentObj = child.comment; const sectionComment = !_.isUndefined(commentObj) ? commentObj.shortText : ''; - const docSection = typeDocUtils._convertEntitiesToDocSection(entities, docsInfo, sectionName); + const isClassOrObjectLiteral = true; + const docSection = typeDocUtils._convertEntitiesToDocSection( + entities, + docsInfo, + sectionName, + isClassOrObjectLiteral, + ); docSection.comment = sectionComment; docAgnosticFormat[sectionName] = docSection; break; @@ -127,7 +133,12 @@ export const typeDocUtils = { return docAgnosticFormat; }, - _convertEntitiesToDocSection(entities: TypeDocNode[], docsInfo: DocsInfo, sectionName: string): DocSection { + _convertEntitiesToDocSection( + entities: TypeDocNode[], + docsInfo: DocsInfo, + sectionName: string, + isClassOrObjectLiteral: boolean = false, + ): DocSection { const docSection: DocSection = { comment: '', constructors: [], @@ -194,6 +205,32 @@ export const typeDocUtils = { } break; + case KindString.Variable: + if (isClassOrObjectLiteral) { + // Render as a property + const property = typeDocUtils._convertProperty( + entity, + docsInfo.sections, + sectionName, + docsInfo.id, + ); + docSection.properties.push(property); + } else { + // Otherwise, render as a type + const customType = typeDocUtils._convertCustomType( + entity, + docsInfo.sections, + sectionName, + docsInfo.id, + ); + const seenTypeNames = _.map(docSection.types, t => t.name); + const isUnseen = !_.includes(seenTypeNames, customType.name); + if (isUnseen) { + docSection.types.push(customType); + } + } + break; + case KindString.Interface: case KindString.Variable: case KindString.Enumeration: @@ -221,6 +258,7 @@ export const typeDocUtils = { throw errorUtils.spawnSwitchErr('kindString', entity.kindString); } }); + console.log('docSection', docSection); return docSection; }, _convertCustomType(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): CustomType { -- cgit v1.2.3 From d9f09b5e1e7ecc8dc56ac7184cfc0152b3c2ff32 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 3 Aug 2018 19:45:09 +0200 Subject: Make rendering of individually exported functions lighter-weight --- packages/react-docs/src/components/documentation.tsx | 10 +++++++++- packages/react-docs/src/docs_info.ts | 11 +++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 4f776b237..5393652d4 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -211,6 +211,14 @@ export class Documentation extends React.Component { return ( @@ -279,7 +287,7 @@ export class Documentation extends React.Component -

Functions

+ {!isExportedFunctionSection &&

Functions

}
{functionDefs}
)} diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index 0637f3e65..36a6a7301 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -52,10 +52,20 @@ export class DocsInfo { return; // no-op } + const isExportedFunctionSection = + docSection.functions.length === 1 && + _.isEmpty(docSection.types) && + _.isEmpty(docSection.methods) && + _.isEmpty(docSection.constructors) && + _.isEmpty(docSection.properties) && + _.isEmpty(docSection.events); + 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 if (isExportedFunctionSection) { + // Noop so that we don't have the method listed underneath itself. } else { let eventNames: string[] = []; if (!_.isUndefined(docSection.events)) { @@ -76,6 +86,7 @@ export class DocsInfo { ]; } }); + console.log('menuSubsectionsBySection', menuSubsectionsBySection); return menuSubsectionsBySection; } public getTypeDefinitionsByName(docAgnosticFormat: DocAgnosticFormat): { [name: string]: TypeDefinitionByName } { -- cgit v1.2.3 From 4527e9ce000d3eafcd55552df0809ea31271ba89 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Sat, 4 Aug 2018 10:09:59 +0200 Subject: Remove prefix hack and add prefix for objectLiteral functions --- packages/react-docs/src/types.ts | 1 + packages/react-docs/src/utils/typedoc_utils.ts | 31 ++++++++++++-------------- 2 files changed, 15 insertions(+), 17 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index 79dfe9f4f..a34e06c94 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -124,6 +124,7 @@ export interface TypescriptMethod extends BaseMethod { export interface TypescriptFunction extends BaseFunction { source?: Source; typeParameter?: TypeParameter; + callPath: string; } export interface SolidityMethod extends BaseMethod { diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 2eee2fa59..b1d9850ef 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -173,6 +173,7 @@ export const typeDocUtils = { docsInfo.sections, sectionName, docsInfo.id, + isClassOrObjectLiteral, ); docSection.functions.push(func); } @@ -331,7 +332,7 @@ export const typeDocUtils = { const commentIfExists = !_.isUndefined(entity.comment) ? entity.comment.shortText : undefined; const isConstructor = false; const isStatic = _.isUndefined(entity.flags.isStatic) ? false : entity.flags.isStatic; - const callPath = typeDocUtils._getCallPath(sectionName, sections, isStatic, isConstructor, docId, entity.name); + const callPath = typeDocUtils._getCallPath(sectionName, isStatic, isConstructor, entity.name); const property = { name: entity.name, type: typeDocUtils._convertType(entity.type, sections, sectionName, docId), @@ -367,7 +368,7 @@ export const typeDocUtils = { ? undefined : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId); - const callPath = typeDocUtils._getCallPath(sectionName, sections, isStatic, isConstructor, docId, entity.name); + const callPath = typeDocUtils._getCallPath(sectionName, isStatic, isConstructor, entity.name); const method = { isConstructor, isStatic, @@ -385,28 +386,16 @@ export const typeDocUtils = { }; return method; }, - _getCallPath( - sectionName: string, - sections: SectionsMap, - isStatic: boolean, - isConstructor: boolean, - docId: string, - entityName: string, - ) { + _getCallPath(sectionName: string, isStatic: boolean, isConstructor: boolean, entityName: string) { // HACK: we use the fact that the sectionName is the same as the property name at the top-level // of the public interface. In the future, we shouldn't use this hack but rather get it from the JSON. let callPath; if (isConstructor || entityName === '__type') { callPath = ''; // TODO: Get rid of this 0x-specific logic - } else if (docId === 'ZERO_EX_JS') { - const topLevelInterface = isStatic ? 'ZeroEx.' : 'zeroEx.'; - callPath = - !_.isUndefined(sections.zeroEx) && sectionName !== sections.zeroEx - ? `${topLevelInterface}${sectionName}.` - : topLevelInterface; } else { - callPath = `${sectionName}.`; + const prefix = isStatic ? sectionName : `${sectionName[0].toLowerCase()}${sectionName.slice(1)}`; + callPath = `${prefix}.`; } return callPath; }, @@ -415,6 +404,7 @@ export const typeDocUtils = { sections: SectionsMap, sectionName: string, docId: string, + isObjectLiteral: boolean, ): TypescriptFunction { const signature = entity.signatures[0]; const source = entity.sources[0]; @@ -428,10 +418,17 @@ export const typeDocUtils = { ? undefined : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId); + let callPath = ''; + if (isObjectLiteral) { + const isConstructor = false; + const isStatic = false; + callPath = typeDocUtils._getCallPath(sectionName, isStatic, isConstructor, entity.name); + } const func = { name: signature.name, comment: hasComment ? signature.comment.shortText : undefined, returnComment: hasComment && signature.comment.returns ? signature.comment.returns : undefined, + callPath, source: { fileName: source.fileName, line: source.line, -- cgit v1.2.3 From ff3c77f7c47475d77defecfeb894a8c86c003997 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Mon, 6 Aug 2018 10:48:18 -0400 Subject: Remove stray console.lgos --- packages/react-docs/src/docs_info.ts | 1 - packages/react-docs/src/utils/typedoc_utils.ts | 4 ---- 2 files changed, 5 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index 36a6a7301..4267d8a98 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -86,7 +86,6 @@ export class DocsInfo { ]; } }); - console.log('menuSubsectionsBySection', menuSubsectionsBySection); return menuSubsectionsBySection; } public getTypeDefinitionsByName(docAgnosticFormat: DocAgnosticFormat): { [name: string]: TypeDefinitionByName } { diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index b1d9850ef..01385c982 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -259,7 +259,6 @@ export const typeDocUtils = { throw errorUtils.spawnSwitchErr('kindString', entity.kindString); } }); - console.log('docSection', docSection); return docSection; }, _convertCustomType(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): CustomType { @@ -352,9 +351,6 @@ export const typeDocUtils = { sectionName: string, docId: string, ): TypescriptMethod { - if (_.isUndefined(entity.signatures)) { - console.log(entity); - } const signature = entity.signatures[0]; const source = entity.sources[0]; const hasComment = !_.isUndefined(signature.comment); -- cgit v1.2.3 From ea5684e0546f25fa213dfb1a780941e4056a2128 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Mon, 6 Aug 2018 11:01:12 -0400 Subject: Remove unused imports --- packages/react-docs/src/components/documentation.tsx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 5393652d4..d9a7dcd59 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -1,9 +1,7 @@ import { - AnchorTitle, colors, constants as sharedConstants, EtherscanLinkSuffixes, - HeaderSizes, MarkdownSection, NestedSidebarMenu, Networks, @@ -28,7 +26,6 @@ import { TypescriptFunction, TypescriptMethod, } from '../types'; -import { constants } from '../utils/constants'; import { Badge } from './badge'; import { Comment } from './comment'; @@ -186,6 +183,7 @@ export class Documentation extends React.Component { return semver.lte(mdVersion, this.props.selectedVersion); }); + console.log('this.props.selectedVersion', this.props.selectedVersion); if (_.isEmpty(eligibleVersions)) { throw new Error( `No eligible markdown sections found for ${this.props.docsInfo.displayName} version ${ -- cgit v1.2.3 From fdcb42d8e17f4f5f324dd644077a07cbd4be65c7 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Mon, 6 Aug 2018 15:27:28 -0400 Subject: Fix bug where we only rendered one TypeDoc JSON key per export, instead of all of them --- packages/react-docs/src/utils/typedoc_utils.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 01385c982..9ee1de2b4 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -60,14 +60,16 @@ export const typeDocUtils = { }, convertToDocAgnosticFormat(generatedDocJson: GeneratedDocJson, docsInfo: DocsInfo): DocAgnosticFormat { const exportPathOrder = generatedDocJson.metadata.exportPathOrder; - const exportPathToTypedocName = generatedDocJson.metadata.exportPathToTypedocName; + const exportPathToTypedocNames = generatedDocJson.metadata.exportPathToTypedocNames; const typeDocJson = generatedDocJson.typedocJson; // TODO: Extract the non typeDoc exports, and render them somehow const typeDocNameOrder = _.compact( - _.map(exportPathOrder, exportPath => { - return exportPathToTypedocName[exportPath]; - }), + _.flatten( + _.map(exportPathOrder, exportPath => { + return exportPathToTypedocNames[exportPath]; + }), + ), ); const docAgnosticFormat: DocAgnosticFormat = {}; @@ -121,6 +123,7 @@ export const typeDocUtils = { }); }); if (!_.isEmpty(typeEntities)) { + console.log('typeEntities', typeEntities); docsInfo.sections[constants.TYPES_SECTION_NAME] = constants.TYPES_SECTION_NAME; docsInfo.menu[constants.TYPES_SECTION_NAME] = [constants.TYPES_SECTION_NAME]; const docSection = typeDocUtils._convertEntitiesToDocSection( -- cgit v1.2.3 From af90a777c6d6cdd59b4d398b6b0f5051047bc5d3 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Mon, 6 Aug 2018 15:27:39 -0400 Subject: Update types --- packages/react-docs/src/types.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index a34e06c94..18c386a2b 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -292,12 +292,12 @@ export enum AbiTypes { Event = 'event', } -export interface ExportNameToTypedocName { - [exportName: string]: string; +export interface ExportNameToTypedocNames { + [exportName: string]: string[]; } export interface Metadata { - exportPathToTypedocName: ExportNameToTypedocName; + exportPathToTypedocNames: ExportNameToTypedocNames; exportPathOrder: string[]; } -- cgit v1.2.3 From 6182d2c7f60967a978f2b885e63fab067794b452 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Mon, 6 Aug 2018 15:28:21 -0400 Subject: Pass in typeDefinitionByName so that type declarations also link to inner-types and show the popover --- packages/react-docs/src/components/documentation.tsx | 13 +++++++++++-- packages/react-docs/src/components/interface.tsx | 19 ++++++++++++++++--- packages/react-docs/src/components/property_block.tsx | 10 ++++++++-- packages/react-docs/src/components/type.tsx | 8 +++++++- .../react-docs/src/components/type_definition.tsx | 12 ++++++++++-- 5 files changed, 52 insertions(+), 10 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index d9a7dcd59..1c32b2e16 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -225,12 +225,16 @@ export class Documentation extends React.Component ); }); const sortedProperties = _.sortBy(docSection.properties, 'name'); - const propertyDefs = _.map(sortedProperties, this._renderProperty.bind(this, sectionName)); + const propertyDefs = _.map( + sortedProperties, + this._renderProperty.bind(this, sectionName, typeDefinitionByName), + ); const sortedMethods = _.sortBy(docSection.methods, 'name'); const methodDefs = _.map(sortedMethods, method => { @@ -349,7 +353,11 @@ export class Documentation extends React.Component{constructorDefs}; } - private _renderProperty(sectionName: string, property: Property): React.ReactNode { + private _renderProperty( + sectionName: string, + typeDefinitionByName: TypeDefinitionByName, + property: Property, + ): React.ReactNode { return ( ); } diff --git a/packages/react-docs/src/components/interface.tsx b/packages/react-docs/src/components/interface.tsx index 915b4bbc6..eaf57ce93 100644 --- a/packages/react-docs/src/components/interface.tsx +++ b/packages/react-docs/src/components/interface.tsx @@ -2,7 +2,7 @@ import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { CustomType } from '../types'; +import { CustomType, TypeDefinitionByName } from '../types'; import { Signature } from './signature'; import { Type } from './type'; @@ -11,6 +11,7 @@ export interface InterfaceProps { type: CustomType; sectionName: string; docsInfo: DocsInfo; + typeDefinitionByName: TypeDefinitionByName; } export const Interface = (props: InterfaceProps) => { @@ -29,9 +30,15 @@ export const Interface = (props: InterfaceProps) => { shouldHideMethodName={true} shouldUseArrowSyntax={true} docsInfo={props.docsInfo} + typeDefinitionByName={props.typeDefinitionByName} /> ) : ( - + )}, ); @@ -41,7 +48,13 @@ export const Interface = (props: InterfaceProps) => { const is = type.indexSignature; const param = ( - {is.keyName}: + {is.keyName}:{' '} + ); properties.push( diff --git a/packages/react-docs/src/components/property_block.tsx b/packages/react-docs/src/components/property_block.tsx index ea80ba7b7..6e5c451be 100644 --- a/packages/react-docs/src/components/property_block.tsx +++ b/packages/react-docs/src/components/property_block.tsx @@ -2,7 +2,7 @@ import { AnchorTitle, HeaderSizes } from '@0xproject/react-shared'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { Property } from '../types'; +import { Property, TypeDefinitionByName } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; @@ -15,6 +15,7 @@ export interface PropertyBlockProps { docsInfo: DocsInfo; sourceUrl: string; selectedVersion: string; + typeDefinitionByName: TypeDefinitionByName; } export interface PropertyBlockState { @@ -50,7 +51,12 @@ export class PropertyBlock extends React.Component {(property as any).callPath} {property.name}:{' '} - + {property.source && ( {is.keyName}:{' '} - + ); typeName = ( @@ -222,6 +227,7 @@ export function Type(props: TypeProps): any { customType={typeDefinition} shouldAddId={false} docsInfo={props.docsInfo} + typeDefinitionByName={props.typeDefinitionByName} /> diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx index 26fbbf75c..775d9890f 100644 --- a/packages/react-docs/src/components/type_definition.tsx +++ b/packages/react-docs/src/components/type_definition.tsx @@ -4,7 +4,7 @@ import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { CustomType, CustomTypeChild, KindString, TypeDocTypes } from '../types'; +import { CustomType, CustomTypeChild, KindString, TypeDocTypes, TypeDefinitionByName } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; @@ -19,6 +19,7 @@ export interface TypeDefinitionProps { customType: CustomType; shouldAddId?: boolean; docsInfo: DocsInfo; + typeDefinitionByName?: TypeDefinitionByName; } export interface TypeDefinitionState { @@ -44,7 +45,12 @@ export class TypeDefinition extends React.Component + ); break; @@ -74,6 +80,7 @@ export class TypeDefinition extends React.Component ) : ( )} -- cgit v1.2.3 From b2b3c24fd231fd78b4af167ff0823d846e8859b4 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Mon, 6 Aug 2018 15:39:11 -0400 Subject: Remove console.log --- packages/react-docs/src/components/documentation.tsx | 1 - 1 file changed, 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 1c32b2e16..f4f1d2aa9 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -183,7 +183,6 @@ export class Documentation extends React.Component { return semver.lte(mdVersion, this.props.selectedVersion); }); - console.log('this.props.selectedVersion', this.props.selectedVersion); if (_.isEmpty(eligibleVersions)) { throw new Error( `No eligible markdown sections found for ${this.props.docsInfo.displayName} version ${ -- cgit v1.2.3 From 1a89905ab9602ccd81c5702bcc13246cd1f6960b Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Mon, 6 Aug 2018 15:39:21 -0400 Subject: Remove hash spy for now --- packages/react-docs/src/components/type.tsx | 1 - 1 file changed, 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 1c580caab..7e96f75c3 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -204,7 +204,6 @@ export function Type(props: TypeProps): any { -- cgit v1.2.3 From ca67e7d36fb5eb91626a60156dbec4f67a7d52f7 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Wed, 8 Aug 2018 09:32:32 -0400 Subject: Remove console.log --- packages/react-docs/src/utils/typedoc_utils.ts | 1 - 1 file changed, 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 9ee1de2b4..b45dc73a8 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -123,7 +123,6 @@ export const typeDocUtils = { }); }); if (!_.isEmpty(typeEntities)) { - console.log('typeEntities', typeEntities); docsInfo.sections[constants.TYPES_SECTION_NAME] = constants.TYPES_SECTION_NAME; docsInfo.menu[constants.TYPES_SECTION_NAME] = [constants.TYPES_SECTION_NAME]; const docSection = typeDocUtils._convertEntitiesToDocSection( -- cgit v1.2.3 From 386b5bb122c189496e83da46cf53e8dfe83f0ee6 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Wed, 8 Aug 2018 09:33:20 -0400 Subject: Add back hashSpy --- packages/react-docs/src/components/type.tsx | 1 + 1 file changed, 1 insertion(+) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 7e96f75c3..1c580caab 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -204,6 +204,7 @@ export function Type(props: TypeProps): any { -- cgit v1.2.3 From cb5d8d75bf03910d1e763eb34907ada296ed3062 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Tue, 14 Aug 2018 17:24:48 -0700 Subject: Link class reference types exported in same package to their declaration --- .../react-docs/src/components/documentation.tsx | 3 +- .../react-docs/src/components/event_definition.tsx | 7 +- packages/react-docs/src/components/interface.tsx | 10 +- .../react-docs/src/components/property_block.tsx | 3 +- packages/react-docs/src/components/signature.tsx | 22 +++- .../react-docs/src/components/signature_block.tsx | 1 + packages/react-docs/src/components/type.tsx | 31 ++++-- .../react-docs/src/components/type_definition.tsx | 7 +- packages/react-docs/src/types.ts | 1 + packages/react-docs/src/utils/typedoc_utils.ts | 122 ++++++++++++++++----- 10 files changed, 163 insertions(+), 44 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index f4f1d2aa9..82e444018 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -30,8 +30,8 @@ import { import { Badge } from './badge'; import { Comment } from './comment'; import { EventDefinition } from './event_definition'; -import { SignatureBlock } from './signature_block'; import { PropertyBlock } from './property_block'; +import { SignatureBlock } from './signature_block'; import { TypeDefinition } from './type_definition'; const networkNameToColor: { [network: string]: string } = { @@ -225,6 +225,7 @@ export class Documentation extends React.Component ); }); diff --git a/packages/react-docs/src/components/event_definition.tsx b/packages/react-docs/src/components/event_definition.tsx index b4dc729a9..6cb80c6b0 100644 --- a/packages/react-docs/src/components/event_definition.tsx +++ b/packages/react-docs/src/components/event_definition.tsx @@ -53,7 +53,12 @@ export class EventDefinition extends React.Component indexed; const eventArgs = _.map(this.props.event.eventArgs, (eventArg: EventArg) => { const type = ( - + ); return ( diff --git a/packages/react-docs/src/components/interface.tsx b/packages/react-docs/src/components/interface.tsx index eaf57ce93..93b10e96d 100644 --- a/packages/react-docs/src/components/interface.tsx +++ b/packages/react-docs/src/components/interface.tsx @@ -7,14 +7,17 @@ import { CustomType, TypeDefinitionByName } from '../types'; import { Signature } from './signature'; import { Type } from './type'; +const defaultProps = {}; + export interface InterfaceProps { type: CustomType; sectionName: string; docsInfo: DocsInfo; typeDefinitionByName: TypeDefinitionByName; + isInPopover: boolean; } -export const Interface = (props: InterfaceProps) => { +export const Interface: React.SFC = (props: InterfaceProps): any => { const type = props.type; const properties = _.map(type.children, property => { return ( @@ -31,6 +34,7 @@ export const Interface = (props: InterfaceProps) => { shouldUseArrowSyntax={true} docsInfo={props.docsInfo} typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} /> ) : ( { sectionName={props.sectionName} docsInfo={props.docsInfo} typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} /> )}, @@ -54,6 +59,7 @@ export const Interface = (props: InterfaceProps) => { sectionName={props.sectionName} docsInfo={props.docsInfo} typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} /> ); @@ -77,3 +83,5 @@ export const Interface = (props: InterfaceProps) => { ); }; + +Interface.defaultProps = defaultProps; diff --git a/packages/react-docs/src/components/property_block.tsx b/packages/react-docs/src/components/property_block.tsx index 6e5c451be..f181e21d2 100644 --- a/packages/react-docs/src/components/property_block.tsx +++ b/packages/react-docs/src/components/property_block.tsx @@ -6,8 +6,8 @@ import { Property, TypeDefinitionByName } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; -import { Type } from './type'; import { SourceLink } from './source_link'; +import { Type } from './type'; export interface PropertyBlockProps { property: Property; @@ -56,6 +56,7 @@ export class PropertyBlock extends React.Component {property.source && ( diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index d9567c9f6..bf9c8be24 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -17,6 +17,7 @@ export interface SignatureProps { typeParameter?: TypeParameter; callPath?: string; docsInfo: DocsInfo; + isInPopover: boolean; } const defaultProps = { @@ -27,7 +28,13 @@ const defaultProps = { export const Signature: React.SFC = (props: SignatureProps) => { const sectionName = props.sectionName; - const parameters = renderParameters(props.parameters, props.docsInfo, sectionName, props.typeDefinitionByName); + const parameters = renderParameters( + props.parameters, + props.docsInfo, + sectionName, + props.isInPopover, + props.typeDefinitionByName, + ); const paramStringArray: any[] = []; // HACK: For now we don't put params on newlines if there are less then 2 of them. // Ideally we would check the character length of the resulting method signature and @@ -57,7 +64,13 @@ export const Signature: React.SFC = (props: SignatureProps) => { const methodName = props.shouldHideMethodName ? '' : props.name; const typeParameterIfExists = _.isUndefined(props.typeParameter) ? undefined - : renderTypeParameter(props.typeParameter, props.docsInfo, sectionName, props.typeDefinitionByName); + : renderTypeParameter( + props.typeParameter, + props.docsInfo, + sectionName, + props.isInPopover, + props.typeDefinitionByName, + ); return ( {props.callPath} @@ -72,6 +85,7 @@ export const Signature: React.SFC = (props: SignatureProps) => { sectionName={sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} /> )} @@ -85,6 +99,7 @@ function renderParameters( parameters: Parameter[], docsInfo: DocsInfo, sectionName: string, + isInPopover: boolean, typeDefinitionByName?: TypeDefinitionByName, ): React.ReactNode[] { const params = _.map(parameters, (p: Parameter) => { @@ -96,6 +111,7 @@ function renderParameters( sectionName={sectionName} typeDefinitionByName={typeDefinitionByName} docsInfo={docsInfo} + isInPopover={isInPopover} /> ); return ( @@ -113,6 +129,7 @@ function renderTypeParameter( typeParameter: TypeParameter, docsInfo: DocsInfo, sectionName: string, + isInPopover: boolean, typeDefinitionByName?: TypeDefinitionByName, ): React.ReactNode { const typeParam = ( @@ -123,6 +140,7 @@ function renderTypeParameter( sectionName={sectionName} typeDefinitionByName={typeDefinitionByName} docsInfo={docsInfo} + isInPopover={isInPopover} /> {`>`} diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index 9e5198e16..934232efe 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -81,6 +81,7 @@ export class SignatureBlock extends React.Component {(method as TypescriptMethod).source && ( diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 1c580caab..eae52e950 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -7,23 +7,26 @@ import * as ReactTooltip from 'react-tooltip'; import { DocsInfo } from '../docs_info'; import { Type as TypeDef, TypeDefinitionByName, TypeDocTypes } from '../types'; +import { constants } from '../utils/constants'; import { Signature } from './signature'; -import { constants } from '../utils/constants'; import { TypeDefinition } from './type_definition'; const basicJsTypes = ['string', 'number', 'undefined', 'null', 'boolean']; +const defaultProps = {}; + export interface TypeProps { type: TypeDef; docsInfo: DocsInfo; sectionName: string; typeDefinitionByName?: TypeDefinitionByName; + isInPopover: boolean; } // The return type needs to be `any` here so that we can recursively define components within // components (e.g when rendering the union type). -export function Type(props: TypeProps): any { +export const Type: React.SFC = (props: TypeProps): any => { const type = props.type; const isReference = type.typeDocType === TypeDocTypes.Reference; const isArray = type.typeDocType === TypeDocTypes.Array; @@ -50,6 +53,7 @@ export function Type(props: TypeProps): any { sectionName={props.sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} />[] ); @@ -61,6 +65,7 @@ export function Type(props: TypeProps): any { sectionName={props.sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} /> ); return subType; @@ -89,6 +94,7 @@ export function Type(props: TypeProps): any { sectionName={props.sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} /> ); }); @@ -110,6 +116,7 @@ export function Type(props: TypeProps): any { shouldUseArrowSyntax={true} docsInfo={props.docsInfo} typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} /> ); } else if (!_.isUndefined(type.indexSignature)) { @@ -122,6 +129,7 @@ export function Type(props: TypeProps): any { sectionName={props.sectionName} docsInfo={props.docsInfo} typeDefinitionByName={props.typeDefinitionByName} + isInPopover={props.isInPopover} /> ); @@ -150,6 +158,7 @@ export function Type(props: TypeProps): any { sectionName={props.sectionName} typeDefinitionByName={props.typeDefinitionByName} docsInfo={props.docsInfo} + isInPopover={props.isInPopover} /> ); }); @@ -180,6 +189,7 @@ export function Type(props: TypeProps): any { ? props.docsInfo.typeConfigs.typeNameToPrefix[typeName as string] : undefined; } + const isExportedClassReference = !!props.type.isExportedClassReference; if (!_.isUndefined(typeNameUrlIfExists)) { typeName = ( - {sharedUtils.isUserOnMobile() ? ( + {sharedUtils.isUserOnMobile() || props.isInPopover || isExportedClassReference ? ( {typeName} ) : ( @@ -248,4 +259,6 @@ export function Type(props: TypeProps): any { )} ); -} +}; + +Type.defaultProps = defaultProps; diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx index 775d9890f..8d1f88490 100644 --- a/packages/react-docs/src/components/type_definition.tsx +++ b/packages/react-docs/src/components/type_definition.tsx @@ -4,7 +4,7 @@ import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { CustomType, CustomTypeChild, KindString, TypeDocTypes, TypeDefinitionByName } from '../types'; +import { CustomType, CustomTypeChild, KindString, TypeDefinitionByName, TypeDocTypes } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; @@ -20,6 +20,7 @@ export interface TypeDefinitionProps { shouldAddId?: boolean; docsInfo: DocsInfo; typeDefinitionByName?: TypeDefinitionByName; + isInPopover?: boolean; } export interface TypeDefinitionState { @@ -29,6 +30,7 @@ export interface TypeDefinitionState { export class TypeDefinition extends React.Component { public static defaultProps: Partial = { shouldAddId: true, + isInPopover: false, }; constructor(props: TypeDefinitionProps) { super(props); @@ -50,6 +52,7 @@ export class TypeDefinition extends React.Component ); break; @@ -81,6 +84,7 @@ export class TypeDefinition extends React.Component ) : ( )} diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index 18c386a2b..c39dfcba8 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -154,6 +154,7 @@ export interface Type { name: string; typeDocType: TypeDocTypes; value?: string; + isExportedClassReference?: boolean; typeArguments?: Type[]; elementType?: ElementType; types?: Type[]; diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index b45dc73a8..ab5408ec2 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -7,6 +7,7 @@ import { CustomTypeChild, DocAgnosticFormat, DocSection, + GeneratedDocJson, IndexSignature, KindString, Parameter, @@ -19,7 +20,6 @@ import { TypeParameter, TypescriptFunction, TypescriptMethod, - GeneratedDocJson, } from '../types'; import { constants } from './constants'; @@ -72,6 +72,15 @@ export const typeDocUtils = { ), ); + const classNames: string[] = []; + _.each(typeDocJson.children, file => { + _.each(file.children, child => { + if (child.kindString === KindString.Class) { + classNames.push(child.name); + } + }); + }); + const docAgnosticFormat: DocAgnosticFormat = {}; const typeEntities: TypeDocNode[] = []; _.each(typeDocNameOrder, typeDocName => { @@ -93,6 +102,7 @@ export const typeDocUtils = { entities, docsInfo, sectionName, + classNames, isClassOrObjectLiteral, ); docSection.comment = sectionComment; @@ -106,7 +116,12 @@ export const typeDocUtils = { const entities = [child]; const commentObj = child.comment; const SectionComment = !_.isUndefined(commentObj) ? commentObj.shortText : ''; - const docSection = typeDocUtils._convertEntitiesToDocSection(entities, docsInfo, sectionName); + const docSection = typeDocUtils._convertEntitiesToDocSection( + entities, + docsInfo, + sectionName, + classNames, + ); docSection.comment = SectionComment; docAgnosticFormat[sectionName] = docSection; break; @@ -129,6 +144,7 @@ export const typeDocUtils = { typeEntities, docsInfo, constants.TYPES_SECTION_NAME, + classNames, ); docAgnosticFormat[constants.TYPES_SECTION_NAME] = docSection; } @@ -139,6 +155,7 @@ export const typeDocUtils = { entities: TypeDocNode[], docsInfo: DocsInfo, sectionName: string, + classNames: string[], isClassOrObjectLiteral: boolean = false, ): DocSection { const docSection: DocSection = { @@ -161,6 +178,7 @@ export const typeDocUtils = { docsInfo.sections, sectionName, docsInfo.id, + classNames, ); docSection.constructors.push(constructor); break; @@ -176,6 +194,7 @@ export const typeDocUtils = { sectionName, docsInfo.id, isClassOrObjectLiteral, + classNames, ); docSection.functions.push(func); } @@ -191,6 +210,7 @@ export const typeDocUtils = { docsInfo.sections, sectionName, docsInfo.id, + classNames, ); docSection.methods.push(method); } @@ -203,6 +223,7 @@ export const typeDocUtils = { docsInfo.sections, sectionName, docsInfo.id, + classNames, ); docSection.properties.push(property); } @@ -216,6 +237,7 @@ export const typeDocUtils = { docsInfo.sections, sectionName, docsInfo.id, + classNames, ); docSection.properties.push(property); } else { @@ -225,6 +247,7 @@ export const typeDocUtils = { docsInfo.sections, sectionName, docsInfo.id, + classNames, ); const seenTypeNames = _.map(docSection.types, t => t.name); const isUnseen = !_.includes(seenTypeNames, customType.name); @@ -235,14 +258,14 @@ export const typeDocUtils = { break; case KindString.Interface: - case KindString.Variable: case KindString.Enumeration: - case KindString.TypeAlias: + case KindString.TypeAlias: { const customType = typeDocUtils._convertCustomType( entity, docsInfo.sections, sectionName, docsInfo.id, + classNames, ); const seenTypeNames = _.map(docSection.types, t => t.name); const isUnseen = !_.includes(seenTypeNames, customType.name); @@ -250,6 +273,7 @@ export const typeDocUtils = { docSection.types.push(customType); } break; + } case KindString.Class: // We currently do not support more then a single class per file @@ -263,18 +287,24 @@ export const typeDocUtils = { }); return docSection; }, - _convertCustomType(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): CustomType { + _convertCustomType( + entity: TypeDocNode, + sections: SectionsMap, + sectionName: string, + docId: string, + classNames: string[], + ): CustomType { const typeIfExists = !_.isUndefined(entity.type) - ? typeDocUtils._convertType(entity.type, sections, sectionName, docId) + ? typeDocUtils._convertType(entity.type, sections, sectionName, docId, classNames) : undefined; const isConstructor = false; const methodIfExists = !_.isUndefined(entity.declaration) - ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId) + ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId, classNames) : undefined; const doesIndexSignatureExist = !_.isUndefined(entity.indexSignature); const indexSignature = entity.indexSignature as TypeDocNode; const indexSignatureIfExists = doesIndexSignatureExist - ? typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId) + ? typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId, classNames) : undefined; const commentIfExists = !_.isUndefined(entity.comment) && !_.isUndefined(entity.comment.shortText) @@ -284,13 +314,20 @@ export const typeDocUtils = { const childrenIfExist = !_.isUndefined(entity.children) ? _.map(entity.children, (child: TypeDocNode) => { let childTypeIfExists = !_.isUndefined(child.type) - ? typeDocUtils._convertType(child.type, sections, sectionName, docId) + ? typeDocUtils._convertType(child.type, sections, sectionName, docId, classNames) : undefined; if (child.kindString === KindString.Method) { childTypeIfExists = { name: child.name, typeDocType: TypeDocTypes.Reflection, - method: typeDocUtils._convertMethod(child, isConstructor, sections, sectionName, docId), + method: typeDocUtils._convertMethod( + child, + isConstructor, + sections, + sectionName, + docId, + classNames, + ), }; } const c: CustomTypeChild = { @@ -319,16 +356,23 @@ export const typeDocUtils = { sections: SectionsMap, sectionName: string, docId: string, + classNames: string[], ): IndexSignature { const key = entity.parameters[0]; const indexSignature = { keyName: key.name, - keyType: typeDocUtils._convertType(key.type, sections, sectionName, docId), + keyType: typeDocUtils._convertType(key.type, sections, sectionName, docId, classNames), valueName: entity.type.name, }; return indexSignature; }, - _convertProperty(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): Property { + _convertProperty( + entity: TypeDocNode, + sections: SectionsMap, + sectionName: string, + docId: string, + classNames: string[], + ): Property { const source = entity.sources[0]; const commentIfExists = !_.isUndefined(entity.comment) ? entity.comment.shortText : undefined; const isConstructor = false; @@ -336,7 +380,7 @@ export const typeDocUtils = { const callPath = typeDocUtils._getCallPath(sectionName, isStatic, isConstructor, entity.name); const property = { name: entity.name, - type: typeDocUtils._convertType(entity.type, sections, sectionName, docId), + type: typeDocUtils._convertType(entity.type, sections, sectionName, docId, classNames), source: { fileName: source.fileName, line: source.line, @@ -352,6 +396,7 @@ export const typeDocUtils = { sections: SectionsMap, sectionName: string, docId: string, + classNames: string[], ): TypescriptMethod { const signature = entity.signatures[0]; const source = entity.sources[0]; @@ -359,12 +404,12 @@ export const typeDocUtils = { const isStatic = _.isUndefined(entity.flags.isStatic) ? false : entity.flags.isStatic; const parameters = _.map(signature.parameters, param => { - return typeDocUtils._convertParameter(param, sections, sectionName, docId); + return typeDocUtils._convertParameter(param, sections, sectionName, docId, classNames); }); - const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId); + const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId, classNames); const typeParameter = _.isUndefined(signature.typeParameter) ? undefined - : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId); + : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId, classNames); const callPath = typeDocUtils._getCallPath(sectionName, isStatic, isConstructor, entity.name); const method = { @@ -384,13 +429,12 @@ export const typeDocUtils = { }; return method; }, - _getCallPath(sectionName: string, isStatic: boolean, isConstructor: boolean, entityName: string) { + _getCallPath(sectionName: string, isStatic: boolean, isConstructor: boolean, entityName: string): string { // HACK: we use the fact that the sectionName is the same as the property name at the top-level // of the public interface. In the future, we shouldn't use this hack but rather get it from the JSON. let callPath; if (isConstructor || entityName === '__type') { callPath = ''; - // TODO: Get rid of this 0x-specific logic } else { const prefix = isStatic ? sectionName : `${sectionName[0].toLowerCase()}${sectionName.slice(1)}`; callPath = `${prefix}.`; @@ -403,18 +447,19 @@ export const typeDocUtils = { sectionName: string, docId: string, isObjectLiteral: boolean, + classNames: string[], ): TypescriptFunction { const signature = entity.signatures[0]; const source = entity.sources[0]; const hasComment = !_.isUndefined(signature.comment); const parameters = _.map(signature.parameters, param => { - return typeDocUtils._convertParameter(param, sections, sectionName, docId); + return typeDocUtils._convertParameter(param, sections, sectionName, docId, classNames); }); - const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId); + const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId, classNames); const typeParameter = _.isUndefined(signature.typeParameter) ? undefined - : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId); + : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId, classNames); let callPath = ''; if (isObjectLiteral) { @@ -442,15 +487,22 @@ export const typeDocUtils = { sections: SectionsMap, sectionName: string, docId: string, + classNames: string[], ): TypeParameter { - const type = typeDocUtils._convertType(entity.type, sections, sectionName, docId); + const type = typeDocUtils._convertType(entity.type, sections, sectionName, docId, classNames); const parameter = { name: entity.name, type, }; return parameter; }, - _convertParameter(entity: TypeDocNode, sections: SectionsMap, sectionName: string, docId: string): Parameter { + _convertParameter( + entity: TypeDocNode, + sections: SectionsMap, + sectionName: string, + docId: string, + classNames: string[], + ): Parameter { let comment = ''; if (entity.comment && entity.comment.shortText) { comment = entity.comment.shortText; @@ -460,7 +512,7 @@ export const typeDocUtils = { const isOptional = !_.isUndefined(entity.flags.isOptional) ? entity.flags.isOptional : false; - const type = typeDocUtils._convertType(entity.type, sections, sectionName, docId); + const type = typeDocUtils._convertType(entity.type, sections, sectionName, docId, classNames); const parameter = { name: entity.name, @@ -471,12 +523,18 @@ export const typeDocUtils = { }; return parameter; }, - _convertType(entity: TypeDocType, sections: SectionsMap, sectionName: string, docId: string): Type { + _convertType( + entity: TypeDocType, + sections: SectionsMap, + sectionName: string, + docId: string, + classNames: string[], + ): Type { const typeArguments = _.map(entity.typeArguments, typeArgument => { - return typeDocUtils._convertType(typeArgument, sections, sectionName, docId); + return typeDocUtils._convertType(typeArgument, sections, sectionName, docId, classNames); }); const types = _.map(entity.types, t => { - return typeDocUtils._convertType(t, sections, sectionName, docId); + return typeDocUtils._convertType(t, sections, sectionName, docId, classNames); }); let indexSignatureIfExists; @@ -485,7 +543,13 @@ export const typeDocUtils = { !_.isUndefined(entity.declaration) && !_.isUndefined(entity.declaration.indexSignature); if (doesIndexSignatureExist) { const indexSignature = entity.declaration.indexSignature as TypeDocNode; - indexSignatureIfExists = typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId); + indexSignatureIfExists = typeDocUtils._convertIndexSignature( + indexSignature, + sections, + sectionName, + docId, + classNames, + ); } else if (!_.isUndefined(entity.declaration)) { const isConstructor = false; methodIfExists = typeDocUtils._convertMethod( @@ -494,6 +558,7 @@ export const typeDocUtils = { sections, sectionName, docId, + classNames, ); } @@ -507,6 +572,7 @@ export const typeDocUtils = { const type = { name: entity.name, value: entity.value, + isExportedClassReference: _.includes(classNames, entity.name), typeDocType: entity.type, typeArguments, elementType: elementTypeIfExists, -- cgit v1.2.3 From 83e3bb899ed88c8ac32331d2f1b533e52d5ad8cd Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Tue, 14 Aug 2018 17:41:03 -0700 Subject: Move purging private underscored items to the doc json generation phase --- .../react-docs/src/components/signature_block.tsx | 3 --- packages/react-docs/src/utils/typedoc_utils.ts | 21 ++++++++------------- 2 files changed, 8 insertions(+), 16 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index 934232efe..2818d9c5f 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -44,9 +44,6 @@ export class SignatureBlock extends React.Component Date: Wed, 15 Aug 2018 11:36:45 -0700 Subject: Move external types to link mapping to doc generation util and refactor typedocUtils to be a class to avoid excessive param passing --- .../react-docs/src/components/signature_block.tsx | 1 - packages/react-docs/src/components/type.tsx | 12 +- packages/react-docs/src/docs_info.ts | 10 +- packages/react-docs/src/types.ts | 12 +- packages/react-docs/src/utils/typedoc_utils.ts | 351 +++++++-------------- 5 files changed, 131 insertions(+), 255 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index 2818d9c5f..05145dc23 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -5,7 +5,6 @@ import * as React from 'react'; import { DocsInfo } from '../docs_info'; import { Parameter, SolidityMethod, TypeDefinitionByName, TypescriptFunction, TypescriptMethod } from '../types'; import { constants } from '../utils/constants'; -import { typeDocUtils } from '../utils/typedoc_utils'; import { Comment } from './comment'; import { Signature } from './signature'; diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index eae52e950..145c797a3 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -179,17 +179,8 @@ export const Type: React.SFC = (props: TypeProps): any => { return [prev, ', ', curr]; }); - let typeNameUrlIfExists; - let typePrefixIfExists; - if (!_.isUndefined(props.docsInfo.typeConfigs)) { - typeNameUrlIfExists = !_.isUndefined(props.docsInfo.typeConfigs.typeNameToExternalLink) - ? props.docsInfo.typeConfigs.typeNameToExternalLink[typeName as string] - : undefined; - typePrefixIfExists = !_.isUndefined(props.docsInfo.typeConfigs.typeNameToPrefix) - ? props.docsInfo.typeConfigs.typeNameToPrefix[typeName as string] - : undefined; - } const isExportedClassReference = !!props.type.isExportedClassReference; + const typeNameUrlIfExists = !_.isUndefined(props.type.externalLink) ? props.type.externalLink : undefined; if (!_.isUndefined(typeNameUrlIfExists)) { typeName = ( = (props: TypeProps): any => { className="text-decoration-none" style={{ color: colors.lightBlueA700 }} > - {!_.isUndefined(typePrefixIfExists) ? `${typePrefixIfExists}.` : ''} {typeName} ); diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index 4267d8a98..9e990ffc5 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -6,17 +6,16 @@ import { ContractsByVersionByNetworkId, DocAgnosticFormat, DocsInfoConfig, - DocsInfoTypeConfigs, DocsMenu, DoxityDocObj, + GeneratedDocJson, SectionNameToMarkdownByVersion, SectionsMap, SupportedDocJson, TypeDefinitionByName, - GeneratedDocJson, } from './types'; import { doxityUtils } from './utils/doxity_utils'; -import { typeDocUtils } from './utils/typedoc_utils'; +import { TypeDocUtils } from './utils/typedoc_utils'; export class DocsInfo { public id: string; @@ -27,7 +26,6 @@ export class DocsInfo { public sections: SectionsMap; public sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion; public contractsByVersionByNetworkId?: ContractsByVersionByNetworkId; - public typeConfigs: DocsInfoTypeConfigs; constructor(config: DocsInfoConfig) { this.id = config.id; this.type = config.type; @@ -37,7 +35,6 @@ export class DocsInfo { this.sections = config.markdownSections; this.sectionNameToMarkdownByVersion = config.sectionNameToMarkdownByVersion; this.contractsByVersionByNetworkId = config.contractsByVersionByNetworkId; - this.typeConfigs = config.typeConfigs; } public getMenuSubsectionsBySection(docAgnosticFormat?: DocAgnosticFormat): MenuSubsectionsBySection { const menuSubsectionsBySection = {} as MenuSubsectionsBySection; @@ -101,7 +98,8 @@ export class DocsInfo { if (this.type === SupportedDocJson.Doxity) { return doxityUtils.convertToDocAgnosticFormat(docObj as DoxityDocObj); } else { - return typeDocUtils.convertToDocAgnosticFormat(docObj as GeneratedDocJson, this); + const typeDocUtils = new TypeDocUtils(docObj as GeneratedDocJson, this); + return typeDocUtils.convertToDocAgnosticFormat(); } } } diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index c39dfcba8..0155685e0 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -11,12 +11,6 @@ export interface DocsInfoConfig { markdownSections: SectionsMap; sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion; contractsByVersionByNetworkId?: ContractsByVersionByNetworkId; - typeConfigs?: DocsInfoTypeConfigs; -} - -export interface DocsInfoTypeConfigs { - typeNameToExternalLink?: { [typeName: string]: string }; - typeNameToPrefix?: { [typeName: string]: string }; } export interface DocsMenu { @@ -160,6 +154,7 @@ export interface Type { types?: Type[]; method?: TypescriptMethod; indexSignature?: IndexSignature; + externalLink?: string; } export interface ElementType { @@ -297,9 +292,14 @@ export interface ExportNameToTypedocNames { [exportName: string]: string[]; } +export interface ExternalTypeToLink { + [externalTypeName: string]: string; +} + export interface Metadata { exportPathToTypedocNames: ExportNameToTypedocNames; exportPathOrder: string[]; + externalTypeToLink: ExternalTypeToLink; } export interface GeneratedDocJson { diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 9843ec9fa..db6063464 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -7,6 +7,7 @@ import { CustomTypeChild, DocAgnosticFormat, DocSection, + ExternalTypeToLink, GeneratedDocJson, IndexSignature, KindString, @@ -24,8 +25,39 @@ import { import { constants } from './constants'; -export const typeDocUtils = { - isType(entity: TypeDocNode): boolean { +export class TypeDocUtils { + private _typeDocNameOrder: string[]; + private _externalTypeToLink: ExternalTypeToLink; + private _docsInfo: DocsInfo; + private _typeDocJson: TypeDocNode; + private _classNames: string[]; + constructor(generatedDocJson: GeneratedDocJson, docsInfo: DocsInfo) { + this._docsInfo = docsInfo; + console.log('generatedDocJson.metadata', generatedDocJson.metadata); + const exportPathOrder = generatedDocJson.metadata.exportPathOrder; + const exportPathToTypedocNames = generatedDocJson.metadata.exportPathToTypedocNames; + this._externalTypeToLink = generatedDocJson.metadata.externalTypeToLink; + this._typeDocJson = generatedDocJson.typedocJson; + + // TODO: Extract the non typeDoc exports, and render them somehow + this._typeDocNameOrder = _.compact( + _.flatten( + _.map(exportPathOrder, exportPath => { + return exportPathToTypedocNames[exportPath]; + }), + ), + ); + + this._classNames = []; + _.each(this._typeDocJson.children, file => { + _.each(file.children, child => { + if (child.kindString === KindString.Class) { + this._classNames.push(child.name); + } + }); + }); + } + public isType(entity: TypeDocNode): boolean { return ( entity.kindString === KindString.Interface || entity.kindString === KindString.Function || @@ -33,17 +65,17 @@ export const typeDocUtils = { entity.kindString === KindString.Variable || entity.kindString === KindString.Enumeration ); - }, - isMethod(entity: TypeDocNode): boolean { + } + public isMethod(entity: TypeDocNode): boolean { return entity.kindString === KindString.Method; - }, - isConstructor(entity: TypeDocNode): boolean { + } + public isConstructor(entity: TypeDocNode): boolean { return entity.kindString === KindString.Constructor; - }, - isProperty(entity: TypeDocNode): boolean { + } + public isProperty(entity: TypeDocNode): boolean { return entity.kindString === KindString.Property; - }, - getModuleDefinitionsBySectionName(versionDocObj: TypeDocNode, configModulePaths: string[]): TypeDocNode[] { + } + public getModuleDefinitionsBySectionName(versionDocObj: TypeDocNode, configModulePaths: string[]): TypeDocNode[] { const moduleDefinitions: TypeDocNode[] = []; const jsonModules = versionDocObj.children; _.each(jsonModules, jsonMod => { @@ -54,52 +86,28 @@ export const typeDocUtils = { }); }); return moduleDefinitions; - }, - convertToDocAgnosticFormat(generatedDocJson: GeneratedDocJson, docsInfo: DocsInfo): DocAgnosticFormat { - const exportPathOrder = generatedDocJson.metadata.exportPathOrder; - const exportPathToTypedocNames = generatedDocJson.metadata.exportPathToTypedocNames; - const typeDocJson = generatedDocJson.typedocJson; - - // TODO: Extract the non typeDoc exports, and render them somehow - const typeDocNameOrder = _.compact( - _.flatten( - _.map(exportPathOrder, exportPath => { - return exportPathToTypedocNames[exportPath]; - }), - ), - ); - - const classNames: string[] = []; - _.each(typeDocJson.children, file => { - _.each(file.children, child => { - if (child.kindString === KindString.Class) { - classNames.push(child.name); - } - }); - }); - + } + public convertToDocAgnosticFormat(): DocAgnosticFormat { const docAgnosticFormat: DocAgnosticFormat = {}; const typeEntities: TypeDocNode[] = []; - _.each(typeDocNameOrder, typeDocName => { - const fileChildIndex = _.findIndex(typeDocJson.children, child => child.name === typeDocName); - const fileChild = typeDocJson.children[fileChildIndex]; + _.each(this._typeDocNameOrder, typeDocName => { + const fileChildIndex = _.findIndex(this._typeDocJson.children, child => child.name === typeDocName); + const fileChild = this._typeDocJson.children[fileChildIndex]; let sectionName: string; _.each(fileChild.children, child => { switch (child.kindString) { case KindString.Class: case KindString.ObjectLiteral: { sectionName = child.name; - docsInfo.sections[sectionName] = sectionName; - docsInfo.menu[sectionName] = [sectionName]; + this._docsInfo.sections[sectionName] = sectionName; + this._docsInfo.menu[sectionName] = [sectionName]; const entities = child.children; const commentObj = child.comment; const sectionComment = !_.isUndefined(commentObj) ? commentObj.shortText : ''; const isClassOrObjectLiteral = true; - const docSection = typeDocUtils._convertEntitiesToDocSection( + const docSection = this._convertEntitiesToDocSection( entities, - docsInfo, sectionName, - classNames, isClassOrObjectLiteral, ); docSection.comment = sectionComment; @@ -108,17 +116,12 @@ export const typeDocUtils = { } case KindString.Function: { sectionName = child.name; - docsInfo.sections[sectionName] = sectionName; - docsInfo.menu[sectionName] = [sectionName]; + this._docsInfo.sections[sectionName] = sectionName; + this._docsInfo.menu[sectionName] = [sectionName]; const entities = [child]; const commentObj = child.comment; const SectionComment = !_.isUndefined(commentObj) ? commentObj.shortText : ''; - const docSection = typeDocUtils._convertEntitiesToDocSection( - entities, - docsInfo, - sectionName, - classNames, - ); + const docSection = this._convertEntitiesToDocSection(entities, sectionName); docSection.comment = SectionComment; docAgnosticFormat[sectionName] = docSection; break; @@ -135,24 +138,17 @@ export const typeDocUtils = { }); }); if (!_.isEmpty(typeEntities)) { - docsInfo.sections[constants.TYPES_SECTION_NAME] = constants.TYPES_SECTION_NAME; - docsInfo.menu[constants.TYPES_SECTION_NAME] = [constants.TYPES_SECTION_NAME]; - const docSection = typeDocUtils._convertEntitiesToDocSection( - typeEntities, - docsInfo, - constants.TYPES_SECTION_NAME, - classNames, - ); + this._docsInfo.sections[constants.TYPES_SECTION_NAME] = constants.TYPES_SECTION_NAME; + this._docsInfo.menu[constants.TYPES_SECTION_NAME] = [constants.TYPES_SECTION_NAME]; + const docSection = this._convertEntitiesToDocSection(typeEntities, constants.TYPES_SECTION_NAME); docAgnosticFormat[constants.TYPES_SECTION_NAME] = docSection; } return docAgnosticFormat; - }, - _convertEntitiesToDocSection( + } + private _convertEntitiesToDocSection( entities: TypeDocNode[], - docsInfo: DocsInfo, sectionName: string, - classNames: string[], isClassOrObjectLiteral: boolean = false, ): DocSection { const docSection: DocSection = { @@ -169,14 +165,7 @@ export const typeDocUtils = { switch (entity.kindString) { case KindString.Constructor: isConstructor = true; - const constructor = typeDocUtils._convertMethod( - entity, - isConstructor, - docsInfo.sections, - sectionName, - docsInfo.id, - classNames, - ); + const constructor = this._convertMethod(entity, isConstructor, sectionName); docSection.constructors.push(constructor); break; @@ -185,14 +174,7 @@ export const typeDocUtils = { const funcName = (entity as TypeDocNode).signatures[0].name; const isPublicFunc = !_.startsWith(funcName, '_'); if (isPublicFunc) { - const func = typeDocUtils._convertFunction( - entity, - docsInfo.sections, - sectionName, - docsInfo.id, - isClassOrObjectLiteral, - classNames, - ); + const func = this._convertFunction(entity, sectionName, isClassOrObjectLiteral); docSection.functions.push(func); } } @@ -201,49 +183,25 @@ export const typeDocUtils = { case KindString.Method: if (entity.flags.isPublic) { isConstructor = false; - const method = typeDocUtils._convertMethod( - entity, - isConstructor, - docsInfo.sections, - sectionName, - docsInfo.id, - classNames, - ); + const method = this._convertMethod(entity, isConstructor, sectionName); docSection.methods.push(method); } break; - case KindString.Property: - const property = typeDocUtils._convertProperty( - entity, - docsInfo.sections, - sectionName, - docsInfo.id, - classNames, - ); + case KindString.Property: { + const property = this._convertProperty(entity, sectionName); docSection.properties.push(property); break; + } case KindString.Variable: if (isClassOrObjectLiteral) { // Render as a property - const property = typeDocUtils._convertProperty( - entity, - docsInfo.sections, - sectionName, - docsInfo.id, - classNames, - ); + const property = this._convertProperty(entity, sectionName); docSection.properties.push(property); } else { // Otherwise, render as a type - const customType = typeDocUtils._convertCustomType( - entity, - docsInfo.sections, - sectionName, - docsInfo.id, - classNames, - ); + const customType = this._convertCustomType(entity, sectionName); const seenTypeNames = _.map(docSection.types, t => t.name); const isUnseen = !_.includes(seenTypeNames, customType.name); if (isUnseen) { @@ -255,13 +213,7 @@ export const typeDocUtils = { case KindString.Interface: case KindString.Enumeration: case KindString.TypeAlias: { - const customType = typeDocUtils._convertCustomType( - entity, - docsInfo.sections, - sectionName, - docsInfo.id, - classNames, - ); + const customType = this._convertCustomType(entity, sectionName); const seenTypeNames = _.map(docSection.types, t => t.name); const isUnseen = !_.includes(seenTypeNames, customType.name); if (isUnseen) { @@ -281,25 +233,17 @@ export const typeDocUtils = { } }); return docSection; - }, - _convertCustomType( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - classNames: string[], - ): CustomType { - const typeIfExists = !_.isUndefined(entity.type) - ? typeDocUtils._convertType(entity.type, sections, sectionName, docId, classNames) - : undefined; + } + private _convertCustomType(entity: TypeDocNode, sectionName: string): CustomType { + const typeIfExists = !_.isUndefined(entity.type) ? this._convertType(entity.type, sectionName) : undefined; const isConstructor = false; const methodIfExists = !_.isUndefined(entity.declaration) - ? typeDocUtils._convertMethod(entity.declaration, isConstructor, sections, sectionName, docId, classNames) + ? this._convertMethod(entity.declaration, isConstructor, sectionName) : undefined; const doesIndexSignatureExist = !_.isUndefined(entity.indexSignature); const indexSignature = entity.indexSignature as TypeDocNode; const indexSignatureIfExists = doesIndexSignatureExist - ? typeDocUtils._convertIndexSignature(indexSignature, sections, sectionName, docId, classNames) + ? this._convertIndexSignature(indexSignature, sectionName) : undefined; const commentIfExists = !_.isUndefined(entity.comment) && !_.isUndefined(entity.comment.shortText) @@ -309,20 +253,13 @@ export const typeDocUtils = { const childrenIfExist = !_.isUndefined(entity.children) ? _.map(entity.children, (child: TypeDocNode) => { let childTypeIfExists = !_.isUndefined(child.type) - ? typeDocUtils._convertType(child.type, sections, sectionName, docId, classNames) + ? this._convertType(child.type, sectionName) : undefined; if (child.kindString === KindString.Method) { childTypeIfExists = { name: child.name, typeDocType: TypeDocTypes.Reflection, - method: typeDocUtils._convertMethod( - child, - isConstructor, - sections, - sectionName, - docId, - classNames, - ), + method: this._convertMethod(child, isConstructor, sectionName), }; } const c: CustomTypeChild = { @@ -345,37 +282,25 @@ export const typeDocUtils = { children: childrenIfExist, }; return customType; - }, - _convertIndexSignature( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - classNames: string[], - ): IndexSignature { + } + private _convertIndexSignature(entity: TypeDocNode, sectionName: string): IndexSignature { const key = entity.parameters[0]; const indexSignature = { keyName: key.name, - keyType: typeDocUtils._convertType(key.type, sections, sectionName, docId, classNames), + keyType: this._convertType(key.type, sectionName), valueName: entity.type.name, }; return indexSignature; - }, - _convertProperty( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - classNames: string[], - ): Property { + } + private _convertProperty(entity: TypeDocNode, sectionName: string): Property { const source = entity.sources[0]; const commentIfExists = !_.isUndefined(entity.comment) ? entity.comment.shortText : undefined; const isConstructor = false; const isStatic = _.isUndefined(entity.flags.isStatic) ? false : entity.flags.isStatic; - const callPath = typeDocUtils._getCallPath(sectionName, isStatic, isConstructor, entity.name); + const callPath = this._getCallPath(sectionName, isStatic, isConstructor, entity.name); const property = { name: entity.name, - type: typeDocUtils._convertType(entity.type, sections, sectionName, docId, classNames), + type: this._convertType(entity.type, sectionName), source: { fileName: source.fileName, line: source.line, @@ -384,29 +309,22 @@ export const typeDocUtils = { callPath, }; return property; - }, - _convertMethod( - entity: TypeDocNode, - isConstructor: boolean, - sections: SectionsMap, - sectionName: string, - docId: string, - classNames: string[], - ): TypescriptMethod { + } + private _convertMethod(entity: TypeDocNode, isConstructor: boolean, sectionName: string): TypescriptMethod { const signature = entity.signatures[0]; const source = entity.sources[0]; const hasComment = !_.isUndefined(signature.comment); const isStatic = _.isUndefined(entity.flags.isStatic) ? false : entity.flags.isStatic; const parameters = _.map(signature.parameters, param => { - return typeDocUtils._convertParameter(param, sections, sectionName, docId, classNames); + return this._convertParameter(param, sectionName); }); - const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId, classNames); + const returnType = this._convertType(signature.type, sectionName); const typeParameter = _.isUndefined(signature.typeParameter) ? undefined - : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId, classNames); + : this._convertTypeParameter(signature.typeParameter[0], sectionName); - const callPath = typeDocUtils._getCallPath(sectionName, isStatic, isConstructor, entity.name); + const callPath = this._getCallPath(sectionName, isStatic, isConstructor, entity.name); const method = { isConstructor, isStatic, @@ -416,6 +334,10 @@ export const typeDocUtils = { source: { fileName: source.fileName, line: source.line, + callPath, + parameters, + returnType, + typeParameter, }, callPath, parameters, @@ -423,8 +345,8 @@ export const typeDocUtils = { typeParameter, }; return method; - }, - _getCallPath(sectionName: string, isStatic: boolean, isConstructor: boolean, entityName: string): string { + } + private _getCallPath(sectionName: string, isStatic: boolean, isConstructor: boolean, entityName: string): string { // HACK: we use the fact that the sectionName is the same as the property name at the top-level // of the public interface. In the future, we shouldn't use this hack but rather get it from the JSON. let callPath; @@ -435,32 +357,25 @@ export const typeDocUtils = { callPath = `${prefix}.`; } return callPath; - }, - _convertFunction( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - isObjectLiteral: boolean, - classNames: string[], - ): TypescriptFunction { + } + private _convertFunction(entity: TypeDocNode, sectionName: string, isObjectLiteral: boolean): TypescriptFunction { const signature = entity.signatures[0]; const source = entity.sources[0]; const hasComment = !_.isUndefined(signature.comment); const parameters = _.map(signature.parameters, param => { - return typeDocUtils._convertParameter(param, sections, sectionName, docId, classNames); + return this._convertParameter(param, sectionName); }); - const returnType = typeDocUtils._convertType(signature.type, sections, sectionName, docId, classNames); + const returnType = this._convertType(signature.type, sectionName); const typeParameter = _.isUndefined(signature.typeParameter) ? undefined - : typeDocUtils._convertTypeParameter(signature.typeParameter[0], sections, sectionName, docId, classNames); + : this._convertTypeParameter(signature.typeParameter[0], sectionName); let callPath = ''; if (isObjectLiteral) { const isConstructor = false; const isStatic = false; - callPath = typeDocUtils._getCallPath(sectionName, isStatic, isConstructor, entity.name); + callPath = this._getCallPath(sectionName, isStatic, isConstructor, entity.name); } const func = { name: signature.name, @@ -476,28 +391,16 @@ export const typeDocUtils = { typeParameter, }; return func; - }, - _convertTypeParameter( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - classNames: string[], - ): TypeParameter { - const type = typeDocUtils._convertType(entity.type, sections, sectionName, docId, classNames); + } + private _convertTypeParameter(entity: TypeDocNode, sectionName: string): TypeParameter { + const type = this._convertType(entity.type, sectionName); const parameter = { name: entity.name, type, }; return parameter; - }, - _convertParameter( - entity: TypeDocNode, - sections: SectionsMap, - sectionName: string, - docId: string, - classNames: string[], - ): Parameter { + } + private _convertParameter(entity: TypeDocNode, sectionName: string): Parameter { let comment = ''; if (entity.comment && entity.comment.shortText) { comment = entity.comment.shortText; @@ -507,7 +410,7 @@ export const typeDocUtils = { const isOptional = !_.isUndefined(entity.flags.isOptional) ? entity.flags.isOptional : false; - const type = typeDocUtils._convertType(entity.type, sections, sectionName, docId, classNames); + const type = this._convertType(entity.type, sectionName); const parameter = { name: entity.name, @@ -517,19 +420,13 @@ export const typeDocUtils = { type, }; return parameter; - }, - _convertType( - entity: TypeDocType, - sections: SectionsMap, - sectionName: string, - docId: string, - classNames: string[], - ): Type { + } + private _convertType(entity: TypeDocType, sectionName: string): Type { const typeArguments = _.map(entity.typeArguments, typeArgument => { - return typeDocUtils._convertType(typeArgument, sections, sectionName, docId, classNames); + return this._convertType(typeArgument, sectionName); }); const types = _.map(entity.types, t => { - return typeDocUtils._convertType(t, sections, sectionName, docId, classNames); + return this._convertType(t, sectionName); }); let indexSignatureIfExists; @@ -538,23 +435,10 @@ export const typeDocUtils = { !_.isUndefined(entity.declaration) && !_.isUndefined(entity.declaration.indexSignature); if (doesIndexSignatureExist) { const indexSignature = entity.declaration.indexSignature as TypeDocNode; - indexSignatureIfExists = typeDocUtils._convertIndexSignature( - indexSignature, - sections, - sectionName, - docId, - classNames, - ); + indexSignatureIfExists = this._convertIndexSignature(indexSignature, sectionName); } else if (!_.isUndefined(entity.declaration)) { const isConstructor = false; - methodIfExists = typeDocUtils._convertMethod( - entity.declaration, - isConstructor, - sections, - sectionName, - docId, - classNames, - ); + methodIfExists = this._convertMethod(entity.declaration, isConstructor, sectionName); } const elementTypeIfExists = !_.isUndefined(entity.elementType) @@ -564,10 +448,10 @@ export const typeDocUtils = { } : undefined; - const type = { + const type: Type = { name: entity.name, value: entity.value, - isExportedClassReference: _.includes(classNames, entity.name), + isExportedClassReference: _.includes(this._classNames, entity.name), typeDocType: entity.type, typeArguments, elementType: elementTypeIfExists, @@ -575,6 +459,11 @@ export const typeDocUtils = { method: methodIfExists, indexSignature: indexSignatureIfExists, }; + console.log('this._externalTypeToLink', this._externalTypeToLink); + const externalLinkIfExists = this._externalTypeToLink[entity.name]; + if (!_.isUndefined(externalLinkIfExists)) { + type.externalLink = externalLinkIfExists; + } return type; - }, -}; + } +} -- cgit v1.2.3 From bf9ee82d9f4a2fec392f0ee58342fc6b3be94dff Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 16 Aug 2018 13:59:50 -0700 Subject: Remove stray console log --- packages/react-docs/src/utils/typedoc_utils.ts | 1 - 1 file changed, 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index db6063464..e10493673 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -33,7 +33,6 @@ export class TypeDocUtils { private _classNames: string[]; constructor(generatedDocJson: GeneratedDocJson, docsInfo: DocsInfo) { this._docsInfo = docsInfo; - console.log('generatedDocJson.metadata', generatedDocJson.metadata); const exportPathOrder = generatedDocJson.metadata.exportPathOrder; const exportPathToTypedocNames = generatedDocJson.metadata.exportPathToTypedocNames; this._externalTypeToLink = generatedDocJson.metadata.externalTypeToLink; -- cgit v1.2.3 From 8e3df2b5aeac9d6776640be1248863055c75cf4a Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 16 Aug 2018 14:57:45 -0700 Subject: Render external dep exports --- .../react-docs/src/components/documentation.tsx | 20 ++++++++++++++++++++ packages/react-docs/src/types.ts | 8 +++++++- packages/react-docs/src/utils/constants.ts | 1 + packages/react-docs/src/utils/typedoc_utils.ts | 21 +++++++++++++++++++-- 4 files changed, 47 insertions(+), 3 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 82e444018..43a1f746e 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -19,6 +19,7 @@ import { AddressByContractName, DocAgnosticFormat, Event, + ExternalExportToLink, Property, SolidityMethod, SupportedDocJson, @@ -26,6 +27,7 @@ import { TypescriptFunction, TypescriptMethod, } from '../types'; +import { constants } from '../utils/constants'; import { Badge } from './badge'; import { Comment } from './comment'; @@ -300,6 +302,8 @@ export class Documentation extends React.Component{eventDefs} )} + {!_.isUndefined(docSection.externalExportToLink) && + this._renderExternalExports(docSection.externalExportToLink)} {!_.isUndefined(typeDefs) && typeDefs.length > 0 && (
@@ -309,6 +313,22 @@ export class Documentation extends React.Component ); } + private _renderExternalExports(externalExportToLink: ExternalExportToLink): React.ReactNode { + const externalExports = _.map(externalExportToLink, (link: string, exportName: string) => { + return ( +
+ + {`import { `} + + {exportName} + + {` } from '${this.props.docsInfo.displayName}'`} + +
+ ); + }); + return
{externalExports}
; + } private _renderNetworkBadgesIfExists(sectionName: string): React.ReactNode { if (this.props.docsInfo.type !== SupportedDocJson.Doxity) { return null; diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index 0155685e0..8352af876 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -105,8 +105,9 @@ export interface DocSection { methods: Array; properties: Property[]; types: CustomType[]; - functions?: TypescriptFunction[]; + functions: TypescriptFunction[]; events?: Event[]; + externalExportToLink?: ExternalExportToLink; } export interface TypescriptMethod extends BaseMethod { @@ -296,10 +297,15 @@ export interface ExternalTypeToLink { [externalTypeName: string]: string; } +export interface ExternalExportToLink { + [externalExport: string]: string; +} + export interface Metadata { exportPathToTypedocNames: ExportNameToTypedocNames; exportPathOrder: string[]; externalTypeToLink: ExternalTypeToLink; + externalExportToLink: ExternalExportToLink; } export interface GeneratedDocJson { diff --git a/packages/react-docs/src/utils/constants.ts b/packages/react-docs/src/utils/constants.ts index c3c74fd11..97bedf2db 100644 --- a/packages/react-docs/src/utils/constants.ts +++ b/packages/react-docs/src/utils/constants.ts @@ -2,6 +2,7 @@ import { SupportedDocJson } from '../types'; export const constants = { TYPES_SECTION_NAME: 'types', + EXTERNAL_EXPORTS_SECTION_NAME: 'externalExports', TYPE_TO_SYNTAX: { [SupportedDocJson.Doxity]: 'solidity', [SupportedDocJson.TypeDoc]: 'typescript', diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index e10493673..989485dfc 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -7,13 +7,13 @@ import { CustomTypeChild, DocAgnosticFormat, DocSection, + ExternalExportToLink, ExternalTypeToLink, GeneratedDocJson, IndexSignature, KindString, Parameter, Property, - SectionsMap, Type, TypeDocNode, TypeDocType, @@ -28,6 +28,7 @@ import { constants } from './constants'; export class TypeDocUtils { private _typeDocNameOrder: string[]; private _externalTypeToLink: ExternalTypeToLink; + private _externalExportToLink: ExternalExportToLink; private _docsInfo: DocsInfo; private _typeDocJson: TypeDocNode; private _classNames: string[]; @@ -36,6 +37,7 @@ export class TypeDocUtils { const exportPathOrder = generatedDocJson.metadata.exportPathOrder; const exportPathToTypedocNames = generatedDocJson.metadata.exportPathToTypedocNames; this._externalTypeToLink = generatedDocJson.metadata.externalTypeToLink; + this._externalExportToLink = generatedDocJson.metadata.externalExportToLink; this._typeDocJson = generatedDocJson.typedocJson; // TODO: Extract the non typeDoc exports, and render them somehow @@ -88,6 +90,22 @@ export class TypeDocUtils { } public convertToDocAgnosticFormat(): DocAgnosticFormat { const docAgnosticFormat: DocAgnosticFormat = {}; + + if (!_.isEmpty(this._externalExportToLink)) { + this._docsInfo.sections[constants.EXTERNAL_EXPORTS_SECTION_NAME] = constants.EXTERNAL_EXPORTS_SECTION_NAME; + this._docsInfo.menu[constants.EXTERNAL_EXPORTS_SECTION_NAME] = [constants.EXTERNAL_EXPORTS_SECTION_NAME]; + const docSection: DocSection = { + comment: 'This package also re-exports some third-party libraries for your convenience.', + constructors: [], + methods: [], + functions: [], + properties: [], + types: [], + externalExportToLink: this._externalExportToLink, + }; + docAgnosticFormat[constants.EXTERNAL_EXPORTS_SECTION_NAME] = docSection; + } + const typeEntities: TypeDocNode[] = []; _.each(this._typeDocNameOrder, typeDocName => { const fileChildIndex = _.findIndex(this._typeDocJson.children, child => child.name === typeDocName); @@ -458,7 +476,6 @@ export class TypeDocUtils { method: methodIfExists, indexSignature: indexSignatureIfExists, }; - console.log('this._externalTypeToLink', this._externalTypeToLink); const externalLinkIfExists = this._externalTypeToLink[entity.name]; if (!_.isUndefined(externalLinkIfExists)) { type.externalLink = externalLinkIfExists; -- cgit v1.2.3 From e47e9c5b34a2c189b6913c4c7082cb7ec256617f Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 16 Aug 2018 15:01:52 -0700 Subject: Fix external exports section name --- packages/react-docs/src/utils/constants.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/constants.ts b/packages/react-docs/src/utils/constants.ts index 97bedf2db..0b08f2c3e 100644 --- a/packages/react-docs/src/utils/constants.ts +++ b/packages/react-docs/src/utils/constants.ts @@ -2,7 +2,7 @@ import { SupportedDocJson } from '../types'; export const constants = { TYPES_SECTION_NAME: 'types', - EXTERNAL_EXPORTS_SECTION_NAME: 'externalExports', + EXTERNAL_EXPORTS_SECTION_NAME: 'external exports', TYPE_TO_SYNTAX: { [SupportedDocJson.Doxity]: 'solidity', [SupportedDocJson.TypeDoc]: 'typescript', -- cgit v1.2.3 From fb637d92347917528e0955e291da5d07006f28e2 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 17 Aug 2018 16:09:04 -0700 Subject: Make sure we don't render protected properties --- packages/react-docs/src/utils/typedoc_utils.ts | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 989485dfc..8ee76c98c 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -76,6 +76,9 @@ export class TypeDocUtils { public isProperty(entity: TypeDocNode): boolean { return entity.kindString === KindString.Property; } + public isUnderscorePrefixed(name: string): boolean { + return _.startsWith(name, '_'); + } public getModuleDefinitionsBySectionName(versionDocObj: TypeDocNode, configModulePaths: string[]): TypeDocNode[] { const moduleDefinitions: TypeDocNode[] = []; const jsonModules = versionDocObj.children; @@ -189,8 +192,7 @@ export class TypeDocUtils { case KindString.Function: if (entity.flags.isExported) { const funcName = (entity as TypeDocNode).signatures[0].name; - const isPublicFunc = !_.startsWith(funcName, '_'); - if (isPublicFunc) { + if (!this.isUnderscorePrefixed(funcName)) { const func = this._convertFunction(entity, sectionName, isClassOrObjectLiteral); docSection.functions.push(func); } @@ -198,7 +200,7 @@ export class TypeDocUtils { break; case KindString.Method: - if (entity.flags.isPublic) { + if (entity.flags.isPublic && !this.isUnderscorePrefixed(entity.name)) { isConstructor = false; const method = this._convertMethod(entity, isConstructor, sectionName); docSection.methods.push(method); @@ -206,8 +208,10 @@ export class TypeDocUtils { break; case KindString.Property: { - const property = this._convertProperty(entity, sectionName); - docSection.properties.push(property); + if (!this.isUnderscorePrefixed(entity.name)) { + const property = this._convertProperty(entity, sectionName); + docSection.properties.push(property); + } break; } -- cgit v1.2.3 From ab7d083aa53f69d98c59529cb708815bf013aa6c Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Tue, 21 Aug 2018 15:39:39 +0100 Subject: Add missing key --- packages/react-docs/src/components/documentation.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 43a1f746e..0adadb30b 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -316,7 +316,7 @@ export class Documentation extends React.Component { return ( -
+
{`import { `} -- cgit v1.2.3 From 809d301d582a01ff70958f380a7f8c4afe898366 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Tue, 21 Aug 2018 17:48:24 +0100 Subject: Fix lowercase names involving ERC acronym --- packages/react-docs/src/utils/typedoc_utils.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 8ee76c98c..0eaf5fd6e 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -374,11 +374,17 @@ export class TypeDocUtils { if (isConstructor || entityName === '__type') { callPath = ''; } else { - const prefix = isStatic ? sectionName : `${sectionName[0].toLowerCase()}${sectionName.slice(1)}`; + const prefix = isStatic ? sectionName : this._getLowercaseSectionName(sectionName); callPath = `${prefix}.`; } return callPath; } + private _getLowercaseSectionName(sectionName: string) { + if (_.startsWith(sectionName, 'ERC')) { + return `${sectionName.slice(0, 3).toLowerCase()}${sectionName.slice(3)}`; + } + return `${sectionName[0].toLowerCase()}${sectionName.slice(1)}`; + } private _convertFunction(entity: TypeDocNode, sectionName: string, isObjectLiteral: boolean): TypescriptFunction { const signature = entity.signatures[0]; const source = entity.sources[0]; -- cgit v1.2.3 From 7c29cadb1722b7ac6df7db8c947cc5eaad24edaf Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Wed, 22 Aug 2018 16:11:42 +0100 Subject: Use actual packageName for external example imports --- packages/react-docs/src/components/documentation.tsx | 2 +- packages/react-docs/src/docs_info.ts | 2 ++ packages/react-docs/src/types.ts | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 0adadb30b..9d9b5141a 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -322,7 +322,7 @@ export class Documentation extends React.Component {exportName} - {` } from '${this.props.docsInfo.displayName}'`} + {` } from '${this.props.docsInfo.packageName}'`}
); diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index 9e990ffc5..f429a34cb 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -21,6 +21,7 @@ export class DocsInfo { public id: string; public type: SupportedDocJson; public displayName: string; + public packageName: string; public packageUrl: string; public menu: DocsMenu; public sections: SectionsMap; @@ -31,6 +32,7 @@ export class DocsInfo { this.type = config.type; this.menu = config.markdownMenu; this.displayName = config.displayName; + this.packageName = config.packageName; this.packageUrl = config.packageUrl; this.sections = config.markdownSections; this.sectionNameToMarkdownByVersion = config.sectionNameToMarkdownByVersion; diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index 8352af876..7fd785e32 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -4,6 +4,7 @@ export interface SectionNameToMarkdownByVersion { export interface DocsInfoConfig { id: string; + packageName: string; type: SupportedDocJson; displayName: string; packageUrl: string; @@ -309,6 +310,7 @@ export interface Metadata { } export interface GeneratedDocJson { + version: string; metadata: Metadata; typedocJson: TypeDocNode; } -- cgit v1.2.3 From b7c119b2aaaa2f3579ca4aeef198eca7f38f1216 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Wed, 22 Aug 2018 18:52:17 +0100 Subject: Fix many linter errors that showed up upon upgrading tsutil --- packages/react-docs/src/utils/typedoc_utils.ts | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 0eaf5fd6e..76443ad81 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -26,12 +26,12 @@ import { import { constants } from './constants'; export class TypeDocUtils { - private _typeDocNameOrder: string[]; - private _externalTypeToLink: ExternalTypeToLink; - private _externalExportToLink: ExternalExportToLink; - private _docsInfo: DocsInfo; - private _typeDocJson: TypeDocNode; - private _classNames: string[]; + private readonly _typeDocNameOrder: string[]; + private readonly _externalTypeToLink: ExternalTypeToLink; + private readonly _externalExportToLink: ExternalExportToLink; + private readonly _docsInfo: DocsInfo; + private readonly _typeDocJson: TypeDocNode; + private readonly _classNames: string[]; constructor(generatedDocJson: GeneratedDocJson, docsInfo: DocsInfo) { this._docsInfo = docsInfo; const exportPathOrder = generatedDocJson.metadata.exportPathOrder; @@ -191,7 +191,7 @@ export class TypeDocUtils { case KindString.Function: if (entity.flags.isExported) { - const funcName = (entity as TypeDocNode).signatures[0].name; + const funcName = entity.signatures[0].name; if (!this.isUnderscorePrefixed(funcName)) { const func = this._convertFunction(entity, sectionName, isClassOrObjectLiteral); docSection.functions.push(func); @@ -262,7 +262,7 @@ export class TypeDocUtils { ? this._convertMethod(entity.declaration, isConstructor, sectionName) : undefined; const doesIndexSignatureExist = !_.isUndefined(entity.indexSignature); - const indexSignature = entity.indexSignature as TypeDocNode; + const indexSignature = entity.indexSignature; const indexSignatureIfExists = doesIndexSignatureExist ? this._convertIndexSignature(indexSignature, sectionName) : undefined; @@ -379,7 +379,7 @@ export class TypeDocUtils { } return callPath; } - private _getLowercaseSectionName(sectionName: string) { + private _getLowercaseSectionName(sectionName: string): string { if (_.startsWith(sectionName, 'ERC')) { return `${sectionName.slice(0, 3).toLowerCase()}${sectionName.slice(3)}`; } @@ -461,7 +461,7 @@ export class TypeDocUtils { const doesIndexSignatureExist = !_.isUndefined(entity.declaration) && !_.isUndefined(entity.declaration.indexSignature); if (doesIndexSignatureExist) { - const indexSignature = entity.declaration.indexSignature as TypeDocNode; + const indexSignature = entity.declaration.indexSignature; indexSignatureIfExists = this._convertIndexSignature(indexSignature, sectionName); } else if (!_.isUndefined(entity.declaration)) { const isConstructor = false; -- cgit v1.2.3 From 610caef73faf735a9b9f38863acee007280151be Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 23 Aug 2018 15:08:02 +0100 Subject: Fix comments --- packages/react-docs/src/utils/typedoc_utils.ts | 1 - 1 file changed, 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 76443ad81..b867b51b4 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -40,7 +40,6 @@ export class TypeDocUtils { this._externalExportToLink = generatedDocJson.metadata.externalExportToLink; this._typeDocJson = generatedDocJson.typedocJson; - // TODO: Extract the non typeDoc exports, and render them somehow this._typeDocNameOrder = _.compact( _.flatten( _.map(exportPathOrder, exportPath => { -- cgit v1.2.3 From 28f077b16f5fc5f08f95bb2ad00724e6ea89dd00 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 23 Aug 2018 16:55:41 +0100 Subject: Add support for rending the Tuple type --- packages/react-docs/src/components/type.tsx | 22 ++++++++++++++++++++++ packages/react-docs/src/types.ts | 8 ++++++++ packages/react-docs/src/utils/typedoc_utils.ts | 6 ++++++ 3 files changed, 36 insertions(+) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 145c797a3..5f7601ce1 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -167,6 +167,28 @@ export const Type: React.SFC = (props: TypeProps): any => { }); break; + case TypeDocTypes.Tuple: + const tupleTypes = _.map(type.tupleElements, t => { + return ( + + ); + }); + typeName = ( +
+ [{_.reduce(tupleTypes, (prev: React.ReactNode, curr: React.ReactNode) => { + return [prev, ', ', curr]; + })}] +
+ ); + break; + default: throw errorUtils.spawnSwitchErr('type.typeDocType', type.typeDocType); } diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index 7fd785e32..f9cb5e26a 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -31,6 +31,12 @@ export interface TypeDocType { declaration: TypeDocNode; elementType?: TypeDocType; indexSignature?: TypeDocNode; + elements?: TupleElement[]; +} + +export interface TupleElement { + type: string; + name: string; } export interface TypeDocFlags { @@ -78,6 +84,7 @@ export enum TypeDocTypes { Union = 'union', TypeParameter = 'typeParameter', Intersection = 'intersection', + Tuple = 'tuple', Unknown = 'unknown', } @@ -157,6 +164,7 @@ export interface Type { method?: TypescriptMethod; indexSignature?: IndexSignature; externalLink?: string; + tupleElements?: Type[]; } export interface ElementType { diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index b867b51b4..67e37e82d 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -457,6 +457,7 @@ export class TypeDocUtils { let indexSignatureIfExists; let methodIfExists; + let tupleElementsIfExists; const doesIndexSignatureExist = !_.isUndefined(entity.declaration) && !_.isUndefined(entity.declaration.indexSignature); if (doesIndexSignatureExist) { @@ -465,6 +466,10 @@ export class TypeDocUtils { } else if (!_.isUndefined(entity.declaration)) { const isConstructor = false; methodIfExists = this._convertMethod(entity.declaration, isConstructor, sectionName); + } else if (entity.type === TypeDocTypes.Tuple) { + tupleElementsIfExists = _.map(entity.elements, el => { + return { name: el.name, typeDocType: el.type as TypeDocTypes }; + }); } const elementTypeIfExists = !_.isUndefined(entity.elementType) @@ -484,6 +489,7 @@ export class TypeDocUtils { types, method: methodIfExists, indexSignature: indexSignatureIfExists, + tupleElements: tupleElementsIfExists, }; const externalLinkIfExists = this._externalTypeToLink[entity.name]; if (!_.isUndefined(externalLinkIfExists)) { -- cgit v1.2.3 From 0ca64e394b8070fde892f61a65a640c7443d5108 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 23 Aug 2018 17:37:40 +0100 Subject: Fix linter --- packages/react-docs/src/utils/typedoc_utils.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'packages/react-docs/src') diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index 67e37e82d..f44945369 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -497,4 +497,4 @@ export class TypeDocUtils { } return type; } -} +} // tslint:disable:max-file-line-count -- cgit v1.2.3