INSTUI-3890 simplify Docs build pipeline

packages/__docs__/buildScripts/DataTypes.mts

@@ -28,7 +28,7 @@ import { Documentation } from 'react-docgen'
 type ProcessedFile =
   Documentation &
   YamlMetaInfo &
-  ParsedJSDoc &
+  JsDocResult &
   PackagePathData &
   { title: string, id:string }
 
@@ -60,23 +60,30 @@ type YamlMetaInfo = {
   tags?: string
 }
 
-type ParsedJSDoc = {
+type JsDocResult = {
+  // the comment section above the function
   comment?: string,
+  // metadata about the parsed file like filename
   meta?: any,
+  // the comment without the comment characters ("/*" etc)
   description?: string,
   kind?: string,
   name?: string,
+  // function params. undefined if the comment is e.g. above imports
   params?: {
     description?: string
     defaultValue?: string | number | boolean
     name: string
     type?: { names: string[] }
     optional?: boolean
   }[],
+  // function return value. undefined if the comment is e.g. above imports
   returns?: JSDocFunctionReturns[],
-  longName?: string,
-  sections?: any[],
-  undocumented?: boolean
+  //e.g. "module:debounce", "module:FocusRegion"
+  longname: string,
+  access?: string,
+  undocumented?: boolean,
+  title?: string
 }
 
 type JSDocFunctionReturns = {
@@ -85,77 +92,61 @@ type JSDocFunctionReturns = {
     names: string[]
   }
 }
-// TODO remove these types, now we can get them directly from react-docgen
+// TODO these are from React-docgen Documentation.d.ts,
+// remove when react-docgen exports them
 interface MethodParameter {
-  name: string
-  type?: TypeDescriptor | null
-  optional?: boolean
+  name: string;
+  description?: string;
+  optional: boolean;
+  type?: TypeDescriptor<FunctionSignatureType> | null;
 }
 
 interface MethodReturn {
-  type: TypeDescriptor | undefined
+  description?: string;
+  type: TypeDescriptor<FunctionSignatureType> | undefined;
 }
 
 interface PropDescriptor {
-  type?: PropTypeDescriptor
-  flowType?: TypeDescriptor
-  tsType?: TypeDescriptor<TSFunctionSignatureType>
-  required?: boolean
-  defaultValue?: any
-  description?: string
+  type?: PropTypeDescriptor;
+  flowType?: TypeDescriptor<FunctionSignatureType>;
+  tsType?: TypeDescriptor<TSFunctionSignatureType>;
+  required?: boolean;
+  defaultValue?: DefaultValueDescriptor;
+  description?: string;
 }
 
 interface PropTypeDescriptor {
-  name:
-    | 'arrayOf'
-    | 'custom'
-    | 'enum'
-    | 'array'
-    | 'bool'
-    | 'func'
-    | 'number'
-    | 'object'
-    | 'string'
-    | 'any'
-    | 'element'
-    | 'node'
-    | 'symbol'
-    | 'objectOf'
-    | 'shape'
-    | 'exact'
-    | 'union'
-    | 'elementType'
-    | 'instanceOf'
-  value?: any
-  raw?: string
-  computed?: boolean
-  // These are only needed for shape/exact types.
-  // Consider consolidating PropTypeDescriptor and PropDescriptor
-  description?: string
-  required?: boolean
+  name: 'any' | 'array' | 'arrayOf' | 'bool' | 'custom' | 'element' | 'elementType' | 'enum' | 'exact' | 'func' | 'instanceOf' | 'node' | 'number' | 'object' | 'objectOf' | 'shape' | 'string' | 'symbol' | 'union';
+  value?: unknown;
+  raw?: string;
+  computed?: boolean;
+  description?: string;
+  required?: boolean;
 }
 
-type TypeDescriptor<T = FunctionSignatureType> =
-  | SimpleType
-  | LiteralType
-  | ElementsType<T>
-  | ObjectSignatureType<T>
-  | T
+type TypeDescriptor<T = FunctionSignatureType> = ElementsType<T> | LiteralType | ObjectSignatureType<T> | SimpleType | T;
 
+interface DefaultValueDescriptor {
+  value: unknown;
+  computed: boolean;
+}
+interface BaseType {
+  required?: boolean;
+  nullable?: boolean;
+  alias?: string;
+}
 interface SimpleType extends BaseType {
-  name: string
-  raw?: string
+  name: string;
+  raw?: string;
 }
-
 interface LiteralType extends BaseType {
-  name: 'literal'
-  value: string
+  name: 'literal';
+  value: string;
 }
-
 interface ElementsType<T = FunctionSignatureType> extends BaseType {
-  name: string
-  raw: string
-  elements: Array<TypeDescriptor<T>>
+  name: string;
+  raw: string;
+  elements: Array<TypeDescriptor<T>>;
 }
 
 interface FunctionArgumentType<T> {
@@ -165,40 +156,33 @@ interface FunctionArgumentType<T> {
 }
 
 interface FunctionSignatureType extends BaseType {
-  name: 'signature'
-  type: 'function'
-  raw: string
+  name: 'signature';
+  type: 'function';
+  raw: string;
   signature: {
-    arguments: Array<FunctionArgumentType<FunctionSignatureType>>
-    return: TypeDescriptor
-  }
+    arguments: Array<FunctionArgumentType<FunctionSignatureType>>;
+    return?: TypeDescriptor<FunctionSignatureType>;
+  };
 }
-
 interface TSFunctionSignatureType extends FunctionSignatureType {
   signature: {
-    arguments: Array<FunctionArgumentType<TSFunctionSignatureType>>
-    return: TypeDescriptor<TSFunctionSignatureType>
-    this?: TypeDescriptor<TSFunctionSignatureType>
-  }
+    arguments: Array<FunctionArgumentType<TSFunctionSignatureType>>;
+    return?: TypeDescriptor<TSFunctionSignatureType>;
+    this?: TypeDescriptor<TSFunctionSignatureType>;
+  };
 }
-
 interface ObjectSignatureType<T = FunctionSignatureType> extends BaseType {
-  name: 'signature'
-  type: 'object'
-  raw: string
+  name: 'signature';
+  type: 'object';
+  raw: string;
   signature: {
     properties: Array<{
-      key: string | TypeDescriptor<T>
-      value: TypeDescriptor<T>
-    }>
-    constructor?: TypeDescriptor<T>
-  }
-}
-
-interface BaseType {
-  required?: boolean
-  nullable?: boolean
-  alias?: string
+      key: TypeDescriptor<T> | string;
+      value: TypeDescriptor<T>;
+      description?: string;
+    }>;
+    constructor?: TypeDescriptor<T>;
+  };
 }
 // end react-docgen part
 
@@ -285,5 +269,5 @@ export type {
   IconGlyph,
   MainDocsData,
   MainIconsData,
-  ParsedJSDoc
+  JsDocResult
 }

packages/__docs__/buildScripts/build-docs.mts

@@ -86,6 +86,7 @@ const pathsToIgnore = [
   '**/__fixtures__/**',
   '**/__testfixtures__/**',
   '**/__tests__/**',
+  '**/__new-tests__/**',
   '**/locales/**',
   '**/styles.{js,ts}',
   '**/theme.{js,ts}',
@@ -179,13 +180,15 @@ function buildDocs() {
 }
 
 // This function is also called by Webpack if a file changes
+// TODO this parses some files twice, its needed for the Webpack watcher but not
+// for the full build.
 function processSingleFile(fullPath: string) {
   let docObject
   const dirName = path.dirname(fullPath)
   const fileName = path.parse(fullPath).name
   if (fileName === 'index') {
     docObject = processFile(fullPath, projectRoot, library)
-    // Components (e.g. Alert) store their descriptions in README.md files.
+    // Some Components (e.g. Alert) store their descriptions in README.md files.
     // Add this to the final JSON if it's edited
     const readmeDesc = tryParseReadme(dirName)
     docObject.description = readmeDesc
@@ -208,6 +211,7 @@ function processSingleFile(fullPath: string) {
       docObject = processFile(fullPath, projectRoot, library)
     }
   } else {
+    // documentation .md files, utils ts and tsx files
     docObject = processFile(fullPath, projectRoot, library)
   }
   const docJSON = JSON.stringify(docObject!)

packages/__docs__/buildScripts/utils/getJSDoc.mts

@@ -25,28 +25,29 @@
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore no typing :(
 import jsdoc from 'jsdoc-api'
-import type { ParsedJSDoc } from '../DataTypes.mjs'
+import type { JsDocResult } from '../DataTypes.mts'
 
 export function getJSDoc(source: Buffer, error: (err: Error) => void) {
-  let doc: ParsedJSDoc = {}
+  // note: JSDoc seems to be abandoned, we should use TypeScript:
+  // https://stackoverflow.com/questions/47429792/is-it-possible-to-get-comments-as-nodes-in-the-ast-using-the-typescript-compiler
+  let doc: Partial<JsDocResult> = {}
   try {
-    const sections = jsdoc
+    // JSDoc only creates these sections if the file has a @module or @namespace annotation
+    let sections: JsDocResult[] = jsdoc
       .explainSync({
         // note: Do not use cache:true here, its buggy
         configure: './jsdoc.config.json',
         source
       })
-      .filter((section: Record<string, any>) => {
+      sections = sections.filter((section) => {
         return (
           section.undocumented !== true &&
           section.access !== 'private' &&
           section.kind !== 'package'
         )
       })
     const module =
-      sections.filter(
-        (section: Record<string, any>) => section.kind === 'module'
-      )[0] ||
+      sections.filter((section) => section.kind === 'module')[0] ||
       sections[0] ||
       {}
     if (process.platform === 'win32' && module.description) {
@@ -55,18 +56,6 @@ export function getJSDoc(source: Buffer, error: (err: Error) => void) {
     }
     doc = {
       ...module,
-      sections: sections
-        .filter(
-          (section: Record<string, any>) => section.longname !== module.longname
-        )
-        .map((section: Record<string, any>) => {
-          const name = section.longname.replace(`${module.longname}.`, '')
-          return {
-            ...section,
-            id: name,
-            title: name
-          }
-        }),
       undocumented: sections.length <= 0
     }
   } catch (err: any) {

packages/__docs__/buildScripts/utils/parseDoc.mts

@@ -26,14 +26,14 @@ import { getJSDoc } from './getJSDoc.mjs'
 import { getReactDoc } from './getReactDoc.mjs'
 import { getFrontMatter } from './getFrontMatter.mjs'
 import path from 'path'
-import type { ParsedJSDoc, YamlMetaInfo } from '../DataTypes.mjs'
+import type { JsDocResult, YamlMetaInfo } from '../DataTypes.mjs'
 import type { Documentation } from 'react-docgen'
 
 export function parseDoc(
   resourcePath: string,
   source: Buffer,
   errorHandler: (err: Error) => void
-): Documentation & YamlMetaInfo & ParsedJSDoc {
+): Documentation & YamlMetaInfo & Partial<JsDocResult> {
   const extension = path.extname(resourcePath)
   const allowedExtensions = ['.js', '.ts', '.tsx']
   let doc: Documentation | undefined

packages/__docs__/package.json

@@ -18,6 +18,7 @@
     "lint": "ui-scripts lint",
     "lint:fix": "ui-scripts lint --fix",
     "build:scripts:ts": "tsc -b tsconfig.node.build.json",
+    "ts:check": "tsc -p tsconfig.build.json --noEmit --emitDeclarationOnly false",
     "clean": "ui-scripts clean",
     "createStatsFile": "mkdirp ./__build__ && webpack --profile --json > __build__/bundleStats.json",
     "analyseStatsFile": "webpack-bundle-analyzer __build__/bundleStats.json"

packages/__docs__/src/App/index.tsx

@@ -101,7 +101,7 @@ class App extends Component<AppProps, AppState> {
   static defaultProps = {
     trayWidth: 300
   }
-  _content?: HTMLDivElement
+  _content?: HTMLDivElement | null
   _menuTrigger?: HTMLButtonElement
   _mediaQueryListener?: ReturnType<typeof addMediaQueryMatchListener>
   _defaultDocumentTitle?: string

packages/__docs__/src/App/props.ts

@@ -28,7 +28,7 @@ import type {
   MainIconsData,
   MainDocsData,
   ProcessedFile
-} from '../../buildScripts/DataTypes'
+} from '../../buildScripts/DataTypes.mts'
 
 type AppOwnProps = {
   trayWidth: number