Add table with config options to docs (#1588)

* Add table with config options to docs * Make config schema more consistent * Update cosmos-config.mdx * Sort options * Install JSON schema types in docs package * Organize code
react-cosmos · Dec 17, 2023 · c9d42ed · c9d42ed
1 parent 6e8136d
commit c9d42ed
Show file tree

Hide file tree

Showing 6 changed files with 95 additions and 12 deletions.
diff --git a/docs/components/ConfigTable.mdx b/docs/components/ConfigTable.mdx
@@ -0,0 +1,28 @@
+import { flattenConfigSchema } from '../utils/flattenConfigSchema';
+
+export function ConfigTable() {
+  const jsonSchema = require('../../packages/react-cosmos/config.schema.json');
+  const configItems = flattenConfigSchema(jsonSchema.properties);
+  return (
+    <table>
+      <thead>
+        <tr>
+          <th>Option</th>
+          <th>Description</th>
+          <th>Default</th>
+        </tr>
+      </thead>
+      <tbody>
+        {configItems.map(item => (
+          <tr key={item.name}>
+            <td>
+              <code>{item.name}</code>
+            </td>
+            <td>{item.description}</td>
+            <td>{item.default && <code>{item.default}</code>}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
diff --git a/docs/package.json b/docs/package.json
@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@svgr/webpack": "8.1.0",
+    "@types/json-schema": "^7.0.15",
     "autoprefixer": "10.4.16",
     "next": "14.0.3",
     "nextra": "2.13.2",

diff --git a/docs/pages/docs/configuration/cosmos-config.mdx b/docs/pages/docs/configuration/cosmos-config.mdx
@@ -1,3 +1,4 @@
+import { ConfigTable } from '../../../components/ConfigTable.mdx';
 import { Callout } from 'nextra/components';
 
 # `cosmos.config.json`
@@ -9,11 +10,6 @@ config editing.
 
 ## Config Schema
 
-<Callout type="info">
-  **To learn about all available options in the Cosmos config see
-  [config.schema.json](https://github.com/react-cosmos/react-cosmos/blob/main/packages/react-cosmos/config.schema.json).**
-</Callout>
-
 You can enhance your Cosmos config with autocomplete in code editors like VS Code.
 
 ```jsonc filename="cosmos.config.json"
@@ -44,3 +40,12 @@ Alternatively, you can reference the local Cosmos config schema in your workspac
   }
 ]
 ```
+
+## Config Options
+
+<Callout type="info">
+  To understand the Cosmos config options in more detail see
+  [config.schema.json](https://github.com/react-cosmos/react-cosmos/blob/main/packages/react-cosmos/config.schema.json).
+</Callout>
+
+<ConfigTable />
diff --git a/docs/utils/flattenConfigSchema.ts b/docs/utils/flattenConfigSchema.ts
@@ -0,0 +1,49 @@
+import { JSONSchema4 } from 'json-schema';
+
+type ConfigItem = {
+  name: string;
+  description: string;
+  default?: string;
+};
+
+export function flattenConfigSchema(
+  properties: JSONSchema4['properties'] = {},
+  prefixes: string[] = []
+) {
+  const items: ConfigItem[] = [];
+
+  Object.keys(properties)
+    .filter(key => !key.startsWith('$'))
+    .filter(key => !['vite', 'webpack', 'ui'].includes(key))
+    .sort((a, b) => a.localeCompare(b))
+    .forEach(key => {
+      const value = properties[key];
+
+      if (value.type === 'object' && value.properties) {
+        items.push(
+          ...flattenConfigSchema(value.properties, [...prefixes, key])
+        );
+      } else {
+        const { description, defaultValue } = parseDesc(value.description);
+        items.push({
+          name: [...prefixes, key].join('.'),
+          description,
+          default: defaultValue,
+        });
+      }
+    });
+
+  return items;
+}
+
+// Parse description with format "This is a description. [default: foo]"
+const descRegex = /^(.+?)( \[default: (.+?)\])?$/;
+
+function parseDesc(description: string = '') {
+  const match = description.match(descRegex);
+
+  return {
+    description: match[1],
+    defaultValue: match[3],
+  };
+}
diff --git a/packages/react-cosmos/config.schema.json b/packages/react-cosmos/config.schema.json
@@ -16,11 +16,11 @@
       "minLength": 1
     },
     "detectLocalPlugins": {
-      "description": "Automatically detect and load local plugins [default: true].",
+      "description": "Automatically detect and load local plugins. [default: true]",
       "type": "boolean"
     },
     "disablePlugins": {
-      "description": "Disable plugins",
+      "description": "Disable plugins. [default: false]",
       "type": "boolean"
     },
     "staticPath": {
@@ -49,7 +49,7 @@
       "minLength": 1
     },
     "ignore": {
-      "description": "Patterns for ignoring fixture and decorator files (eg. [\"**/dist/**\"]]).",
+      "description": "Patterns for ignoring fixture and decorator files (eg. [\"**/dist/**\"]).",
       "type": "array",
       "items": { "type": "string", "minLength": 1 },
       "uniqueItems": true
@@ -93,17 +93,17 @@
       "additionalProperties": false,
       "properties": {
         "certPath": {
-          "description": "Path of a certificate file",
+          "description": "Path of a certificate file.",
           "type": "string"
         },
         "keyPath": {
-          "description": "Path of a certificate's key file",
+          "description": "Path of a certificate's key file.",
           "type": "string"
         }
       }
     },
     "httpProxy": {
-      "description": "Proxy some URLs to a different HTTP server (eg. an API backend dev server). Similar to devServer.proxy in webpack config.",
+      "description": "Proxy some URLs to a different HTTP server (eg. an API backend dev server).",
       "type": "object",
       "additionalProperties": true,
       "patternProperties": {

diff --git a/yarn.lock b/yarn.lock
@@ -2761,7 +2761,7 @@
     "@types/tough-cookie" "*"
     parse5 "^7.0.0"
 
-"@types/json-schema@*", "@types/json-schema@^7.0.12", "@types/json-schema@^7.0.8", "@types/json-schema@^7.0.9":
+"@types/json-schema@*", "@types/json-schema@^7.0.12", "@types/json-schema@^7.0.15", "@types/json-schema@^7.0.8", "@types/json-schema@^7.0.9":
   version "7.0.15"
   resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.15.tgz#596a1747233694d50f6ad8a7869fcb6f56cf5841"
   integrity sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==