Merge #812

812: docs(Reference): Combine front-end and dgeni parsing for api reference. r=davemneo a=afragapane ### Description of the Change Combine front-end and dgeni parsing to create working API reference. ### Test Plan View website and confirm things look as expected. ### Applicable Issues #702 Co-authored-by: afragapane <ahfragapane@gmail.com>
neo-one-suite · Jan 3, 2019 · bbde4a7 · bbde4a7
2 parents a3e0251 + 2fa998b
commit bbde4a7
Show file tree

Hide file tree

Showing 18 changed files with 508 additions and 421 deletions.
diff --git a/packages/neo-one-website/src/components/reference/ReferenceGrid.tsx b/packages/neo-one-website/src/components/reference/ReferenceGrid.tsx
@@ -11,7 +11,7 @@ const { useState } = React;
 const ReferenceLayout = styled(Box)`
   display: grid;
   min-width: 0;
-  grid-template-columns: repeat(auto-fill, 240px);
+  grid-template-columns: repeat(auto-fill, 400px);
   grid-gap: 8px;
 `;
 

diff --git a/packages/neo-one-website/src/components/reference/common/TypeIcon.tsx b/packages/neo-one-website/src/components/reference/common/TypeIcon.tsx
@@ -14,12 +14,12 @@ const IconBox = styled(Box)<{ readonly bg: TypeFilterOptions; readonly fullIcon:
   background-color: ${switchProp('bg', {
     All: 'transparent',
     Class: prop('theme.primary'),
-    Const: prop('theme.secondary'),
-    Function: prop('theme.accent'),
-    Interface: prop('theme.error'),
-    Enum: prop('theme.warning'),
-    Decorator: prop('theme.gray3'),
-    'Type Alias': prop('theme.gray6'),
+    Const: prop('theme.gray6'),
+    Function: prop('theme.warning'),
+    Interface: prop('theme.accent'),
+    Enum: prop('theme.gray3'),
+    Decorator: prop('theme.error'),
+    'Type Alias': prop('theme.secondary'),
   })};
   color: ${switchProp(
     'bg',

diff --git a/packages/neo-one-website/src/components/reference/common/utils.tsx b/packages/neo-one-website/src/components/reference/common/utils.tsx
@@ -8,31 +8,51 @@ import { Prism } from '../../../common';
 import { RouterLink } from '../../RouterLink';
 import { WordTokens } from '../types';
 
-const ReferenceLink = styled(Link.withComponent(RouterLink))<{ readonly code?: boolean }>`
+const PUNCTUATION: ReadonlyArray<string> = ['.', ',', '(', ')', '[', ']', '{', '}', '<', '>', ';', ':'];
+
+const checkPunctuation = (idx: number, example: WordTokens, value: string) =>
+  PUNCTUATION.includes(value) || (idx !== example.length - 1 && PUNCTUATION.includes(example[idx + 1].value))
+    ? `${value}`
+    : `${value} `;
+
+const StyledReferenceLink = styled(Link.withComponent(RouterLink))<{ readonly code?: boolean }>`
   font-family: ${ifProp('code', "Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace")};
-  ${ifProp('code', prop('theme.fontStyles.subheading'))};
+  ${prop('theme.fontStyles.subheading')};
 `;
 
+interface Props {
+  readonly to: string;
+  readonly value: string;
+  readonly idx: number;
+  readonly example: WordTokens;
+  readonly code?: boolean;
+}
+
+const ReferenceLink = ({ to, value, idx, example, code = false, ...props }: Props) => (
+  <StyledReferenceLink to={to} linkColor="accent" code={code} key={idx} {...props}>
+    {checkPunctuation(idx, example, value)}
+  </StyledReferenceLink>
+);
+
 export const buildExample = (example: WordTokens) =>
   example.map((token, idx) =>
     token.slug === undefined ? (
       <span key={idx}>
-        {new Parser().parse(Prism.highlight(`${token.value} `, Prism.languages.typescript, 'typescript'), 'text/xml')}
+        {new Parser().parse(
+          Prism.highlight(checkPunctuation(idx, example, token.value), Prism.languages.typescript, 'typescript'),
+          'text/xml',
+        )}
       </span>
     ) : (
-      <ReferenceLink to={token.slug} linkColor="accent" code key={idx}>
-        {`${token.value} `}
-      </ReferenceLink>
+      <ReferenceLink to={token.slug} code idx={idx} value={token.value} example={example} />
     ),
   );
 
 export const buildText = (example: WordTokens) =>
   example.map((token, idx) =>
     token.slug === undefined ? (
-      <span key={idx}>{`${token.value} `}</span>
+      <span key={idx}>{checkPunctuation(idx, example, token.value)}</span>
     ) : (
-      <ReferenceLink to={token.slug} linkColor="accent" key={idx}>
-        {`${token.value} `}
-      </ReferenceLink>
+      <ReferenceLink to={token.slug} idx={idx} value={token.value} example={example} />
     ),
   );
diff --git a/packages/neo-one-website/src/components/reference/components/Extra.tsx b/packages/neo-one-website/src/components/reference/components/Extra.tsx
@@ -1,3 +1,4 @@
+// tslint:disable no-null-keyword
 import { Box } from '@neo-one/react-common';
 import * as React from 'react';
 import styled from 'styled-components';
@@ -21,7 +22,7 @@ interface Props {
 
 export const Extra = ({ data, ...props }: Props) => (
   <Wrapper {...props}>
-    {data.title === undefined ? undefined : <Title>{data.title}</Title>}
+    {data.title === undefined ? null : <Title>{data.title}</Title>}
     {data.code ? <Example example={data.data} /> : <Text text={data.data} />}
   </Wrapper>
 );
diff --git a/packages/neo-one-website/src/components/reference/components/InterfaceClassItems.tsx b/packages/neo-one-website/src/components/reference/components/InterfaceClassItems.tsx
@@ -1,4 +1,6 @@
+// tslint:disable no-null-keyword
 import { Box } from '@neo-one/react-common';
+import _ from 'lodash';
 import * as React from 'react';
 import styled from 'styled-components';
 import { prop } from 'styled-tools';
@@ -24,15 +26,18 @@ const Wrapper = styled(Box)`
 
 export const InterfaceClassItems = ({ data, ...props }: Props) => (
   <Wrapper {...props}>
-    {data.constructorDefinition === undefined ? (
-      undefined
-    ) : (
+    {data.constructorDefinition === undefined ? null : (
       <Wrapper>
         <Title>Constructor</Title>
         <MethodItem method={data.constructorDefinition} />
       </Wrapper>
     )}
-    {data.properties === undefined ? undefined : <ParameterPropertyList values={data.properties} title="Properties" />}
-    {data.methods === undefined ? undefined : <MethodList methods={data.methods} />}
+    {data.properties === undefined || _.isEmpty(data.properties) ? null : (
+      <ParameterPropertyList values={data.properties} title="Properties" />
+    )}
+    {data.staticMethods === undefined || _.isEmpty(data.staticMethods) ? null : (
+      <MethodList methods={data.staticMethods} staticMethods />
+    )}
+    {data.methods === undefined || _.isEmpty(data.methods) ? null : <MethodList methods={data.methods} />}
   </Wrapper>
 );
diff --git a/packages/neo-one-website/src/components/reference/components/MethodItem.tsx b/packages/neo-one-website/src/components/reference/components/MethodItem.tsx
@@ -1,9 +1,11 @@
+// tslint:disable no-null-keyword
 import { Box } from '@neo-one/react-common';
 import * as React from 'react';
 import styled from 'styled-components';
 import { prop } from 'styled-tools';
 import { Example, Text, Title } from '../common';
 import { Method } from '../types';
+import { Extra } from './Extra';
 import { ParameterReturns } from './ParameterReturns';
 
 export interface Props {
@@ -43,9 +45,10 @@ export const MethodItem = ({ method, ...props }: Props) => (
   <Layout {...props}>
     <StyledTitle subheading>{method.title}</StyledTitle>
     <Wrapper>
-      {method.description === undefined ? undefined : <Text text={method.description} />}
+      {method.description === undefined ? null : <Text text={method.description} />}
       <Example example={method.definition} />
       <ParameterReturns functionData={method.functionData} subheading />
+      {method.extra === undefined ? null : method.extra.map((extra) => <Extra data={extra} key={extra.title} />)}
     </Wrapper>
   </Layout>
 );
diff --git a/packages/neo-one-website/src/components/reference/components/MethodList.tsx b/packages/neo-one-website/src/components/reference/components/MethodList.tsx
@@ -18,11 +18,12 @@ const ParameterLayout = styled(Box)`
 
 interface Props {
   readonly methods: ReadonlyArray<Method>;
+  readonly staticMethods?: boolean;
 }
 
-export const MethodList = ({ methods, ...props }: Props) => (
+export const MethodList = ({ methods, staticMethods, ...props }: Props) => (
   <ParameterLayout {...props}>
-    <Title>Methods</Title>
+    <Title>{staticMethods ? 'Static Methods' : 'Methods'}</Title>
     {methods.map((method) => (
       <MethodItem key={method.title} method={method} />
     ))}

diff --git a/packages/neo-one-website/src/components/reference/components/ParameterPropertyItem.tsx b/packages/neo-one-website/src/components/reference/components/ParameterPropertyItem.tsx
@@ -1,3 +1,4 @@
+// tslint:disable no-null-keyword
 import { Box } from '@neo-one/react-common';
 import * as React from 'react';
 import styled from 'styled-components';
@@ -27,7 +28,7 @@ interface Props {
 export const ParameterPropertyItem = ({ value, ...props }: Props) => (
   <ParameterLayout {...props}>
     <Name>{value.name}</Name>
-    {value.type === undefined ? undefined : <Text text={value.type} />}
+    {value.type === undefined ? null : <Text text={value.type} />}
     <Text text={value.description} />
   </ParameterLayout>
 );
diff --git a/packages/neo-one-website/src/components/reference/components/ParameterReturns.tsx b/packages/neo-one-website/src/components/reference/components/ParameterReturns.tsx
@@ -1,4 +1,6 @@
+// tslint:disable no-null-keyword
 import { Box } from '@neo-one/react-common';
+import _ from 'lodash';
 import * as React from 'react';
 import styled from 'styled-components';
 import { prop } from 'styled-tools';
@@ -23,14 +25,10 @@ const Wrapper = styled(Box)`
 
 export const ParameterReturns = ({ functionData, subheading, ...props }: Props) => (
   <Wrapper {...props}>
-    {functionData.parameters === undefined ? (
-      undefined
-    ) : (
+    {functionData.parameters === undefined || _.isEmpty(functionData.parameters) ? null : (
       <ParameterPropertyList values={functionData.parameters} title="Parameters" subheading={subheading} />
     )}
-    {functionData.returns === undefined ? (
-      undefined
-    ) : (
+    {functionData.returns === undefined || _.isEmpty(functionData.returns) ? null : (
       <TextSection title="Returns" text={functionData.returns} subheading={subheading} />
     )}
   </Wrapper>

diff --git a/packages/neo-one-website/src/components/reference/components/ReferencePage.tsx b/packages/neo-one-website/src/components/reference/components/ReferencePage.tsx
@@ -1,3 +1,4 @@
+// tslint:disable no-null-keyword
 import { Box } from '@neo-one/react-common';
 import * as React from 'react';
 import styled from 'styled-components';
@@ -25,14 +26,13 @@ const PageLayout = styled(Box)`
 export const ReferencePage = ({ content, ...props }: Props) => (
   <PageLayout {...props}>
     <ReferenceHeader type={content.type} description={content.description} definition={content.definition} />
-    {content.functionData === undefined ? undefined : <ParameterReturns functionData={content.functionData} />}
-    {content.classData === undefined ? undefined : <InterfaceClassItems data={content.classData} />}
-    {content.enumData === undefined ? (
-      undefined
-    ) : (
+    {content.functionData === undefined ? null : <ParameterReturns functionData={content.functionData} />}
+    {content.classData === undefined ? null : <InterfaceClassItems data={content.classData} />}
+    {content.enumData === undefined ? null : (
       <ParameterPropertyList values={content.enumData.members} title="Members" />
     )}
-    {content.interfaceData === undefined ? undefined : <InterfaceClassItems data={content.interfaceData} />}
-    {content.extra === undefined ? undefined : content.extra.map((extra) => <Extra data={extra} key={extra.title} />)}
+    {content.constData === undefined ? null : <InterfaceClassItems data={content.constData} />}
+    {content.interfaceData === undefined ? null : <InterfaceClassItems data={content.interfaceData} />}
+    {content.extra === undefined ? null : content.extra.map((extra) => <Extra data={extra} key={extra.title} />)}
   </PageLayout>
 );
diff --git a/packages/neo-one-website/src/components/reference/types.ts b/packages/neo-one-website/src/components/reference/types.ts
@@ -14,7 +14,7 @@ export const TYPE_FILTER_OPTIONS: ReadonlyArray<TypeFilterOptions> = [
 ];
 
 export interface WordToken {
-  readonly slug: string | undefined;
+  readonly slug?: string | undefined;
   readonly value: string;
 }
 
@@ -36,6 +36,7 @@ export interface Method {
   readonly title: string;
   readonly description?: WordTokens;
   readonly definition: WordTokens;
+  readonly extra?: ReadonlyArray<ExtraData>;
 }
 
 export interface Property extends Parameter {}
@@ -44,6 +45,7 @@ export interface InterfaceData {
   readonly constructorDefinition?: Method;
   readonly properties?: ReadonlyArray<Property>;
   readonly methods?: ReadonlyArray<Method>;
+  readonly staticMethods?: ReadonlyArray<Method>;
 }
 
 export interface ClassData extends InterfaceData {}
@@ -54,6 +56,8 @@ export interface EnumData {
   readonly members: ReadonlyArray<EnumMember>;
 }
 
+export interface ConstData extends InterfaceData {}
+
 export interface ExtraData {
   readonly title?: string;
   readonly code?: boolean;
@@ -69,6 +73,7 @@ export interface ReferenceItem {
   readonly functionData?: FunctionData;
   readonly classData?: ClassData;
   readonly enumData?: EnumData;
+  readonly constData?: ConstData;
   readonly interfaceData?: InterfaceData;
   readonly extra?: ReadonlyArray<ExtraData>;
 }
diff --git a/packages/neo-one-website/src/pages/referenceRedirect.tsx b/packages/neo-one-website/src/pages/referenceRedirect.tsx
@@ -0,0 +1,25 @@
+// tslint:disable strict-type-predicates
+// tslint:disable-next-line no-import-side-effect
+import '../polyfill';
+
+import { Redirect } from '@reach/router';
+import * as React from 'react';
+import { RouteData } from 'react-static';
+import { Helmet } from '../components';
+import { DocsLoading } from '../layout';
+
+interface ReferenceRedirectProps {
+  readonly redirect: string;
+}
+
+// tslint:disable-next-line:no-default-export export-name
+export default () => (
+  <>
+    <Helmet title="NEO•ONE Reference" />
+    {/*
+    // @ts-ignore */}
+    <RouteData Loader={DocsLoading}>
+      {({ redirect }: ReferenceRedirectProps) => <Redirect to={redirect} noThrow={typeof window === 'undefined'} />}
+    </RouteData>
+  </>
+);
diff --git a/packages/neo-one-website/src/utils/dgeniSetup.ts b/packages/neo-one-website/src/utils/dgeniSetup.ts
@@ -58,12 +58,10 @@ const docFiles: ReadonlyArray<string> = [
       },
     });
 
-    // Configure output path for overloaded functions. Each overload needs a unique output file to avoid conflict.
     computePathsProcessor.pathTemplates.push({
-      docTypes: ['function-overload'],
+      docTypes: ['const', 'interface', 'class', 'type-alias', 'decorator', 'function', 'enum'],
       outputPathTemplate: 'partials/modules/${path}/index.html',
-      // Template to generate unique path for each overload of a function.
-      pathTemplate: '${moduleDoc.path}/${name}${parameterDocs.length}',
+      pathTemplate: '${moduleDoc.path}/${docType}/${name}',
     });
   });