feat: extract props table block for docs

ccontrols · Mar 26, 2020 · a6bfbd2 · a6bfbd2
1 parent 00ceda6
commit a6bfbd2
Show file tree

Hide file tree

Showing 10 changed files with 103 additions and 89 deletions.
diff --git a/README.md b/README.md
@@ -84,6 +84,8 @@ Webpack loader that injects the data collected by [@component-controls/instrumen
 
 # UI packages
 
+The UI libraries are built around [theme-ui](https://theme-ui.com) and are designed to abstract the user interface level of components.
+
 <package-section file="./ui/components/README.md" section="overview" />
 
 <!-- START-PACKAGE-SECTION -->
@@ -148,6 +150,10 @@ Some of the guiding design goals for this library:
 
 # Props info
 
+The props-info packages are designed to solidify prop tables extraction for components. Every props-info package must export a props extractor factory that is initialized with the options for the specific library and returns a function that can parse a file and extract prop tables.
+
+The props-info libraries are specifically meant to be used only at build-time, as they can add significant overhead to the sites at run-time.
+
 <package-section file="./props-info/react-docgen/README.md" section="overview" />
 
 <!-- START-PACKAGE-SECTION -->

diff --git a/core/loader/README.md b/core/loader/README.md
@@ -41,33 +41,18 @@ _defined in [@component-controls/loader/src/story-store-data.ts](https://github.
 
 
 
-### properties
-
-| Name | Type | Description |
-| ---- | ---- | ----------- |
-
 ## injectedStories
 
 _defined in [@component-controls/loader/src/story-store-data.ts](https://github.com/ccontrols/component-controls/tree/master/core/loader/src/story-store-data.ts#L6)_
 
 
 
-### properties
-
-| Name | Type | Description |
-| ---- | ---- | ----------- |
-
 ## storyStore
 
 _defined in [@component-controls/loader/src/story-store-data.ts](https://github.com/ccontrols/component-controls/tree/master/core/loader/src/story-store-data.ts#L8)_
 
 
 
-### properties
-
-| Name | Type | Description |
-| ---- | ---- | ----------- |
-
 ## loadStoryStore
 
 _defined in [@component-controls/loader/src/story-store-data.ts](https://github.com/ccontrols/component-controls/tree/master/core/loader/src/story-store-data.ts#L10)_

diff --git a/scripts/blocks/props-table.ts b/scripts/blocks/props-table.ts
@@ -0,0 +1,59 @@
+import { Node, NodeChildren } from '../common/types';
+
+export interface PropItem {
+  name: string;
+  isOptional: boolean;
+  type: Node[];
+  description: string;
+}
+
+
+export const createPropsRow = ({ name, isOptional, type, description }: PropItem): NodeChildren => {
+  return { type : 'tableRow' , children: [
+    { type: 'tableCell', children: [ { type: 'inlineCode', value: `${name}${isOptional ? '': '*'}`}]},
+    {
+      type: 'tableCell',
+      children: type,
+    },
+    {
+      type: 'tableCell',
+      children: [{ type: 'text', value: description }],
+    }
+  ]}
+}
+
+export const createPropsTable = (title: string, children: PropItem[]): { propsTable: Node[], table?: NodeChildren}  => {
+  const propsTable: Node[] = [];
+  let table: NodeChildren | undefined;
+  if (children) {
+    propsTable.push({
+      type: 'paragraph',
+      children: [{
+        type: 'heading',
+        depth: 3,
+        children: [{
+          type: 'text',
+          value: title,
+        }]
+      }]  
+    })
+    table = {
+      type: 'table',
+      children: [
+        { type: 'tableRow', children: [
+          { type: 'tableCell', children: [ { type: 'text', value: 'Name'}]},
+          { type: 'tableCell', children: [ { type: 'text', value: 'Type'}]},
+          { type: 'tableCell', children: [ { type: 'text', value: 'Description'}]},
+        ]}
+      ]
+    }
+    propsTable.push({
+      type: 'paragraph',
+      children: [table]
+    });
+    table.children.push.apply(table.children,
+      children.map((child: PropItem) => createPropsRow(child))
+    );
+  }
+  return { propsTable, table };
+}
diff --git a/scripts/package-info.ts → scripts/common/package-info.ts b/scripts/package-info.ts → scripts/common/package-info.ts
diff --git a/scripts/types.ts → scripts/common/types.ts b/scripts/types.ts → scripts/common/types.ts
diff --git a/scripts/utils.ts → scripts/common/utils.ts b/scripts/utils.ts → scripts/common/utils.ts
diff --git a/scripts/overview-sections/insert-overview.ts b/scripts/overview-sections/insert-overview.ts
@@ -1,8 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import remark from 'remark';
-import { Node } from '../types';
-import { extractCustomTag, inlineNewContent } from '../utils';
+import { Node } from '../common/types';
+import { extractCustomTag, inlineNewContent } from '../common/utils';
 
 export const insertOverview = () => {
   return  (node: Node ) => {

diff --git a/scripts/react-docgen-typescript/insert-react-docgen-typescript.ts b/scripts/react-docgen-typescript/insert-react-docgen-typescript.ts
@@ -6,8 +6,8 @@ import {
   PropItem,
   ParserOptions,
 } from 'react-docgen-typescript';
-import { Settings, Node, NodeChildren } from '../types';
-import { extractCustomTag, inlineNewContent, traverseDirs }from '../utils';
+import { Settings, Node, NodeChildren } from '../common/types';
+import { extractCustomTag, inlineNewContent, traverseDirs }from '../common/utils';
 
 const propsToMDNodes = (propTable: ComponentDoc, repoFileName: string) => {
   const nodes: Node[] = [];

diff --git a/scripts/tsdoc/extract-tsdoc.ts b/scripts/tsdoc/extract-tsdoc.ts
@@ -2,9 +2,9 @@ import path from 'path';
 import fs from 'fs';
 import { Application } from 'typedoc';
 import { ModuleKind, ScriptTarget } from 'typescript';
-import { getRepoPath } from '../package-info';
-
-import { Node, NodeChildren } from '../types';
+import { getRepoPath } from '../common/package-info';
+import { createPropsRow, createPropsTable, PropItem } from '../blocks/props-table';
+import { Node, NodeChildren } from '../common/types';
 
 const app = new Application();
 app.bootstrap({
@@ -23,68 +23,31 @@ export const extractTSDoc = (files: string[], entries: string[]): Node[] | undef
   const addedTypeNames: string[] = [];
   const repoNames: { [key: string]: { repo?: string, filePath?: string, packageName?: string, relativePath?: string} } = {};
 
-  const createPropsRpw = (name: string, isOptional: boolean, type: any, comment: string): NodeChildren => {
-    return { type : 'tableRow' , children: [
-      { type: 'tableCell', children: [ { type: 'inlineCode', value: `${name}${isOptional ? '': '*'}`}]},
-      {
-        type: 'tableCell',
-        children: type,
-      },
-      {
-        type: 'tableCell',
-        children: [{ type: 'text', value: comment }],
-      }
-    ]}
-  }
   const extractPropTable = (nodes: Node[], title: string): { propsTable: Node[], table?: NodeChildren} => {
-    const propsTable: Node[] = [];
-    let table: NodeChildren | undefined;
-    if (nodes) {
-      propsTable.push({
-        type: 'paragraph',
-        children: [{
-          type: 'heading',
-          depth: 3,
-          children: [{
-            type: 'text',
-            value: title,
-          }]
-        }]  
-      })
-      table = {
-        type: 'table',
-        children: [
-          { type: 'tableRow', children: [
-            { type: 'tableCell', children: [ { type: 'text', value: 'Name'}]},
-            { type: 'tableCell', children: [ { type: 'text', value: 'Type'}]},
-            { type: 'tableCell', children: [ { type: 'text', value: 'Description'}]},
-          ]}
-        ]
-      }
-      propsTable.push({
-        type: 'paragraph',
-        children: [table]
-      });
-      nodes.forEach && nodes.forEach((child: any) => {
-        if (child.declaration) {
-          //@ts-ignore
-          table.children.push.apply(table.children, child.declaration.children.map((d: any) => createPropsRpw(
-            d.name,
-            d.flags ? d.flags.isOptional : true,
-            d.type ? extractPropType(d.type) : extractFunction(d, false),
-            d.comment ? d.comment.shortText : '')));
-        } else {
-          const tableRow: NodeChildren = createPropsRpw(
-            child.name,
-            child.flags ? child.flags.isOptional : true,
-            child.type ? extractPropType(child.type.type ? child.type: child) : extractFunction(child, false),
-            child.comment ? child.comment.shortText : '');
-          //@ts-ignore
-          table.children.push(tableRow);
-          }  
-      });
+    const props: PropItem[] = nodes && nodes.map && nodes.reduce((acc: any, child: any) => {
+      if (child.declaration) {
+        return [
+          ...acc,
+          ...child.declaration.children.map((d: any) => ({
+          name: d.name,
+          isOptional: d.flags ? d.flags.isOptional : true,
+          type: d.type ? extractPropType(d.type) : extractFunction(d, false),
+          description: d.comment ? d.comment.shortText : ''
+        }))
+      ];
+    } else {
+      return [
+        ...acc,
+        {
+          name: child.name,
+          isOptional: child.flags ? child.flags.isOptional : true,
+          type: child.type ? extractPropType(child.type.type ? child.type: child) : extractFunction(child, false),
+          description: child.comment ? child.comment.shortText : ''
+        }
+      ]
     }
-    return { propsTable, table };
+    }, []);  
+    return createPropsTable(title, props);
   }
   const extractFunction = (node: any, extractTable: boolean = true): Node[] => {
     const result: Node[] = [];
@@ -164,11 +127,12 @@ export const extractTSDoc = (files: string[], entries: string[]): Node[] | undef
         if (extractTable) {
           const { propsTable, table } = extractPropTable(signature.parameters, 'parameters');
           if (table && signature.type) {
-            table.children.push(createPropsRpw(
-              'returns',
-              true,
-              extractPropType(signature.type),
-              signature.comment ? signature.comment.returns : ''))
+            table.children.push(createPropsRow({
+              name: 'returns',
+              isOptional: true,
+              type: extractPropType(signature.type),
+              description: signature.comment ? signature.comment.returns : ''
+            }))
           }
           result.push.apply(result, propsTable);
         }  

diff --git a/scripts/tsdoc/insert-tsdoc.ts b/scripts/tsdoc/insert-tsdoc.ts
@@ -1,6 +1,6 @@
 import path from 'path';
-import { Settings, Node } from '../types';
-import { extractCustomTag, inlineNewContent } from '../utils';
+import { Settings, Node } from '../common/types';
+import { extractCustomTag, inlineNewContent } from '../common/utils';
 import { extractTSDoc } from './extract-tsdoc';
 
 export const insertTSDoc = (settings: Settings = { path: './src' }) => {