@patternfly/documentation-framework 2.0.0-alpha.21 → 2.0.0-alpha.23

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 2.0.0-alpha.23 (2023-04-17)
+
+
+### Features
+
+* **docs-framework:** add support for exposing function documentation ([#3485](https://github.com/patternfly/patternfly-org/issues/3485)) ([2f19ded](https://github.com/patternfly/patternfly-org/commit/2f19deda84c75042df1870c0950bb173eb2c3d84))
+
+
+
+
+
+# 2.0.0-alpha.22 (2023-04-17)
+
+**Note:** Version bump only for package @patternfly/documentation-framework
+
+
+
+
+
 # 2.0.0-alpha.21 (2023-04-15)
 
 

package/components/functionsTable/functionsTable.js

@@ -0,0 +1,57 @@
+import React from "react";
+import {
+  Table,
+  Caption,
+  Thead,
+  Tr,
+  Th,
+  Tbody,
+  Td,
+} from "@patternfly/react-table";
+
+export const FunctionsTable = ({ functionDescriptions }) => {
+  const columnNames = {
+    name: "Function name",
+    description: "Description",
+    signature: "Type signature",
+    defaultValues: "Default parameter values",
+  };
+
+  const formatDefaultValues = (parameters) =>
+    parameters.map((param) => `${param.name}: ${param.default}; `);
+
+  return (
+    <Table
+      aria-label="Function documentation table"
+      variant="compact"
+    >
+      <Caption>Table showing documentation for relevant functions</Caption>
+      <Thead>
+        <Tr>
+          <Th>{columnNames.name}</Th>
+          <Th>{columnNames.signature}</Th>
+          <Th>{columnNames.defaultValues}</Th>
+          <Th>{columnNames.description}</Th>
+        </Tr>
+      </Thead>
+      <Tbody>
+        {functionDescriptions.map((functionDescription) => (
+          <Tr key={functionDescription.functionName}>
+            <Td dataLabel={columnNames.name}>
+              {functionDescription.functionName}
+            </Td>
+            <Td dataLabel={columnNames.signature}>
+              {functionDescription.type}
+            </Td>
+            <Td dataLabel={columnNames.defaultValues}>
+              {formatDefaultValues(functionDescription.params)}
+            </Td>
+            <Td dataLabel={columnNames.description}>
+              {functionDescription.description}
+            </Td>
+          </Tr>
+        ))}
+      </Tbody>
+    </Table>
+  );
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@patternfly/documentation-framework",
   "description": "A framework to build documentation for PatternFly.",
-  "version": "2.0.0-alpha.21",
+  "version": "2.0.0-alpha.23",
   "author": "Red Hat",
   "license": "MIT",
   "private": false,
@@ -69,6 +69,7 @@
     "sharp": "0.30.6",
     "style-to-object": "0.3.0",
     "to-vfile": "6.1.0",
+    "typedoc": "0.22.X",
     "typescript": "4.3.5",
     "unified": "9.1.0",
     "unist-util-remove": "2.0.0",
@@ -89,5 +90,5 @@
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0"
   },
-  "gitHead": "527165f722646aff84364fd888e6c676da746a77"
+  "gitHead": "8b1251f4f498ce3704dbb4446dd5e7ebf6725bee"
 }

package/scripts/cli/generate.js

@@ -1,5 +1,5 @@
 const path = require('path');
-const { sourceMD, sourceProps, writeIndex } = require('../md/parseMD');
+const { sourceMD, sourceProps, sourceFunctionDocs, writeIndex } = require('../md/parseMD');
 
 function getSource(options) {
   return require(path.join(process.cwd(), options.parent.source));
@@ -9,7 +9,7 @@ function generate(options) {
   const start = new Date();
   console.log('write source files to patternfly-docs/generated');
   const sourceMDWithOptions = (glob, source, ignore) => sourceMD(glob, source, ignore, options._name);
-  getSource(options)(sourceMDWithOptions, sourceProps);
+  getSource(options)(sourceMDWithOptions, sourceProps, sourceFunctionDocs);
   const exitCode = writeIndex();
   if (exitCode !== 0) {
     process.exit(exitCode);

package/scripts/md/parseMD.js

@@ -12,10 +12,12 @@ const { typecheck } = require('./typecheck');
 const { makeSlug } = require('../../helpers/slugger');
 const { liveCodeTypes } = require('../../helpers/liveCodeTypes');
 const { tsDocgen } = require('../tsDocgen');
+const { getPackageFunctionDocumentation } = require("../typeDocGen");
 
 let exitCode = 0;
 const outputBase = path.join(process.cwd(), `patternfly-docs/generated`);
 const tsDocs = {};
+let functionDocs = {};
 const routes = {};
 const globs = {
   props: [],
@@ -75,6 +77,24 @@ function toReactComponent(mdFilePath, source, buildMode) {
         return acc;
       }, []);
 
+      const functionDocumentation = Object.keys(
+        frontmatter.functions || {}
+      ).reduce((acc, fileName) => {
+        const functionNames = frontmatter.functions[fileName];
+
+        functionNames.forEach((functionName) => {
+          if (functionDocs[fileName] && functionDocs[fileName][functionName]) {
+            const functionDescriptionWithName = { functionName, ...functionDocs[fileName][functionName]}
+            acc.push(functionDescriptionWithName);
+          } else {
+            file.message(
+              `function documentation for ${functionName} is missing from function docs generation`
+            );
+          }
+        });
+        return acc;
+      }, []);
+
       const normalizedPath = relPath
         .replace('node_modules/@patternfly/patternfly/docs', 'src/patternfly')
         .replace(/node_modules\/@patternfly\/react-([\w-])/, (_, match) => `packages/react-${match}`)
@@ -107,6 +127,9 @@ function toReactComponent(mdFilePath, source, buildMode) {
       if (propComponents.length > 0) {
         pageData.propComponents = propComponents;
       }
+      if (functionDocumentation.length > 0) {
+        pageData.functionDocumentation = functionDocumentation;
+      }
       if (frontmatter.optIn) {
         pageData.optIn = frontmatter.optIn;
       }
@@ -275,6 +298,10 @@ function sourceMDFile(file, source, buildMode) {
   }
 }
 
+function sourceFunctionDocs(packageName) {
+  functionDocs = getPackageFunctionDocumentation(packageName);
+}
+
 function writeIndex() {
   const stringifyRoute = ([route, pageData]) => `'${route}': {\n    ${Object.entries(pageData)
     .map(([key, val]) => `${key}: ${JSON.stringify(val)}`)
@@ -313,6 +340,7 @@ module.exports = {
     globs.md.push({ glob, source, ignore });
     sync(glob, { ignore }).forEach(file => sourceMDFile(file, source, buildMode));
   },
+  sourceFunctionDocs,
   writeIndex,
   watchMD() {
     globs.props.forEach(({ glob, ignore }) => {

package/scripts/typeDocGen.js

@@ -0,0 +1,209 @@
+const TypeDoc = require("typedoc");
+const path = require("path");
+
+/** Compiles variable types if a type is generic. */
+function getVariableType(typeArguments) {
+  if (!typeArguments || typeArguments.length === 0) {
+    return "";
+  }
+
+  const typeArgs = typeArguments.map((type) => getType(type));
+
+  return (
+    typeArgs.reduce((acc, type) => acc + type + ", ", "<").slice(0, -2) + ">"
+  );
+}
+
+/** compiles key/value pairs of a Type or Interface. */
+function getPropertyTypes(properties) {
+  const formattedProperties = properties.reduce((acc, property) => {
+    const { flags, name, type } = property;
+    const formattedName = flags.isOptional ? name + "?" : name;
+    return `${acc}${formattedName}: ${getType(type)}; `;
+  }, "");
+
+  return `{ ${formattedProperties} }`;
+}
+
+/** Compiles the subtypes of a tuple. */
+function getTupleTypes(tupleElements) {
+  const [firstType, secondType] = tupleElements.map((element) =>
+    getType(element)
+  );
+  return `[${firstType}, ${secondType}]`;
+}
+
+/** Compiles the different subtypes of a union or intersection. */
+function getJoinedTypes(types, joinChar) {
+  const joinedTypes = types.map((type) => getType(type));
+  return joinedTypes
+    .reduce((acc, type) => `${acc} ${joinChar} ${type}`, "")
+    .slice(2);
+}
+
+/** Return the type of a reflection.
+ * For anything that has, or can have, multiple subtypes (i.e. variable types in a generic, properties in an interface,
+ * several types in a union, callbacks, etc.) it will recursively navigate the parsed type info as needed to resolve
+ * all relevant subtypes.
+ */
+function getType(reflection) {
+  switch (reflection.type) {
+    case "intrinsic":
+    case "reference":
+      return reflection.name + getVariableType(reflection.typeArguments);
+    case "union":
+      return getJoinedTypes(reflection.types, "|");
+    case "reflection":
+      const { signatures, children } = reflection.declaration;
+      if (signatures) {
+        return getFunctionDocumentation(signatures[0]).type;
+      } else if (children) {
+        return getPropertyTypes(children);
+      } else {
+        return "Props";
+      }
+    case "array":
+      return reflection.elementType.name + "[]";
+    case "tuple":
+      return getTupleTypes(reflection.elements);
+    case "intersection":
+      return getJoinedTypes(reflection.types, "&");
+    case "literal":
+      return reflection.value;
+  }
+}
+
+/** Compiles information about the parameters of a function.
+ * Includes the name, default value, type, and whether it is optional.
+ */
+function getParamInfo(parameters = []) {
+  return parameters.map((parameter) => {
+    const { name, defaultValue, type, flags } = parameter;
+    return {
+      name,
+      default: defaultValue,
+      type: getType(type),
+      optional: flags.isOptional,
+    };
+  });
+}
+
+/** Formats call signature for a function. */
+function formatFunctionType(parameters, returnType) {
+  const annotatedParams = parameters.map((parameter) => {
+    const { name, type, optional } = parameter;
+
+    return [optional ? name + "?" : name, type];
+  });
+
+  const formattedParams = annotatedParams
+    .reduce((acc, param) => `${acc}, ${param[0]}: ${param[1]}`, "")
+    .slice(2);
+
+  return `(${formattedParams}) => ${returnType}`;
+}
+
+/** Primary entry point for gathering type information from a typedoc function reflection. */
+function getFunctionDocumentation(callSignatureReflection) {
+  const { type, parameters, comment } = callSignatureReflection;
+  const params = getParamInfo(parameters);
+
+  const returnType = type?.name || getType(type);
+
+  return {
+    params,
+    returnType,
+    type: formatFunctionType(params, returnType),
+    description: comment?.shortText,
+  };
+}
+
+/** Parses the source for a package using TypeDoc. */
+function typeDocGen(entryPoint, tsconfigLocation) {
+  const app = new TypeDoc.Application();
+  app.options.addReader(new TypeDoc.TSConfigReader());
+  app.bootstrap({
+    // typedoc options here
+    entryPointStrategy: "expand",
+    entryPoints: [entryPoint],
+    tsconfig: tsconfigLocation,
+  });
+
+  // this non-standard reflection creation allows us to ignore any type errors in a package
+  const project = app.converter.convert(app.getEntryPoints() ?? []);
+
+  // if something caused project conversion to fail log an error
+  if (project) {
+    return project;
+  } else {
+    console.error("Something went wrong during typedoc project conversion");
+    return {};
+  }
+}
+
+/** Takes package information and returns an object with all tsdoc standard format info about the functions in it.
+ * 
+ * The object has file names as keys, with values being an additional object which has the function names in that file
+ * as keys and the information about that function as the value, also in object form.
+ * Information includes the name of the file in which it's defined, the parameters, description, default values and
+ * type information.
+ *
+ * Example structure:
+ * {
+ *   "components/component.tsx": {
+ *     "boolToString": {
+ *       "description": "Converts a boolean to a string",
+ *       "params": [
+ *         {
+ *           "default": false,
+ *           "name": "booleanValue",
+ *           "optional": true,
+ *           "type": "boolean",
+ *         },
+ *       ],
+ *       "returnType": "string",
+ *       "type": "(booleanValue?: boolean) => string",
+ *     },
+ *   },
+ * }
+ */
+function getPackageFunctionDocumentation(
+  packageName,
+  pathToRoot = "dist/js/index.js",
+  srcPath = "src",
+  tsconfigPath = "tsconfig.json"
+) {
+  const packageRoot = require.resolve(packageName).replace(pathToRoot, "");
+  const entry = path.relative(process.cwd(), path.join(packageRoot, srcPath));
+  const configLocation = path.relative(
+    process.cwd(),
+    path.join(packageRoot, tsconfigPath)
+  );
+
+  const packageReflection = typeDocGen(entry, configLocation);
+
+  // 64 corresponds with functions, see all reflection kinds here: https://typedoc.org/api/enums/Models.ReflectionKind-1.html
+  const functionReflections = packageReflection.getReflectionsByKind(64);
+
+  const functionsMap = functionReflections.reduce((acc, functionReflection) => {
+    const { name, sources, signatures } = functionReflection;
+
+    const sourceFile = sources[0].fileName;
+    const shortSourceFile = sourceFile.replace(
+      `${packageName}/${srcPath}/`,
+      ""
+    );
+    const obj = getFunctionDocumentation(signatures[0]);
+
+    if (acc[shortSourceFile]) {
+      acc[shortSourceFile] = { ...acc[shortSourceFile], [name]: obj };
+    } else {
+      acc[shortSourceFile] = { [name]: obj };
+    }
+    return acc;
+  }, {});
+
+  return functionsMap;
+}
+
+module.exports = { getPackageFunctionDocumentation };

package/templates/mdx.js

@@ -7,6 +7,7 @@ import { CSSVariables, PropsTable, TableOfContents, Link, AutoLinkHeader, Inline
 import { capitalize, getTitle, slugger, trackEvent } from '../helpers';
 import './mdx.css';
 import { convertToReactComponent } from '@patternfly/ast-helpers';
+import { FunctionsTable } from '../components/functionsTable/functionsTable';
 
 const MDXChildTemplate = ({
   Component,
@@ -19,7 +20,8 @@ const MDXChildTemplate = ({
     sourceLink,
     cssPrefix = [],
     optIn,
-    beta
+    beta,
+    functionDocumentation = []
   } = Component.getPageData();
   const cssVarsTitle = cssPrefix.length > 0 && 'CSS variables';
   const propsTitle = propComponents.length > 0 && 'Props';
@@ -69,6 +71,14 @@ const MDXChildTemplate = ({
         <div className="ws-mdx-content-content">
           {InlineAlerts}
           <Component />
+          {functionDocumentation.length > 0 && (
+            <React.Fragment>
+              <AutoLinkHeader size="h2" className="ws-h2" id="functions">
+                Functions
+              </AutoLinkHeader>
+              <FunctionsTable functionDescriptions={functionDocumentation}/>
+            </React.Fragment>
+          )}
           {propsTitle && (
             <React.Fragment>
               <AutoLinkHeader size="h2" className="ws-h2" id="props">