Fix compodoc generation for angular sandboxes

storybookjs · Jan 12, 2023 · 090cf83 · 090cf83
1 parent 9b014bb
commit 090cf83
Show file tree

Hide file tree

Showing 4 changed files with 128 additions and 31 deletions.
diff --git a/code/addons/docs/angular/README.md b/code/addons/docs/angular/README.md
@@ -13,6 +13,8 @@ To learn more about Storybook Docs, read the [general documentation](../README.m
 - [Installation](#installation)
 - [DocsPage](#docspage)
 - [Props tables](#props-tables)
+  - [Automatic Compodoc setup](#automatic-compodoc-setup)
+- [Manual Compodoc setup](#manual-compodoc-setup)
 - [MDX](#mdx)
 - [IFrame height](#iframe-height)
 - [Inline Stories](#inline-stories)
@@ -42,35 +44,63 @@ When you [install docs](#installation) you should get basic [DocsPage](../docs/d
 
 Getting [Props tables](../docs/props-tables.md) for your components requires a few more steps. Docs for Angular relies on [Compodoc](https://compodoc.app/), the excellent API documentation tool. It supports `inputs`, `outputs`, `properties`, `methods`, `view/content child/children` as first class prop types.
 
-To get this, you'll first need to install Compodoc:
+### Automatic Compodoc setup
+
+During `sb init`, you will be asked, whether you want to setup Compodoc for your project. Just answer the question with Yes. Compodoc is then ready to use!
+
+## Manual Compodoc setup
+
+You'll need to register Compodoc's `documentation.json` file in `.storybook/preview.ts`:
+
+```js
+import { setCompodocJson } from '@storybook/addon-docs/angular';
+import docJson from '../documentation.json';
+
+setCompodocJson(docJson);
+```
+
+Finally, to set up compodoc, you'll first need to install Compodoc:
 
 ```sh
 yarn add -D @compodoc/compodoc
 ```
 
-Then you'll need to configure Compodoc to generate a `documentation.json` file. Adding the following snippet to your `package.json` creates a metadata file `./documentation.json` each time you run storybook:
+Then you'll need to configure Compodoc to generate a `documentation.json` file. Adding the following snippet to your `projects.<project>.architect.<storybook|build-storybook>` in the `angular.json` creates a metadata file `./documentation.json` each time you run storybook:
 
-```json
+```jsonc
+// angular.json
 {
-  ...
-  "scripts": {
-    "docs:json": "compodoc -p ./tsconfig.json -e json -d .",
-    "storybook": "npm run docs:json && start-storybook -p 6006 -s src/assets",
-    ...
-  },
+  "projects": {
+    "your-project": {
+      "architect": {
+        "storybook": {
+          ...,
+          "compodoc": true,
+          "compodocArgs": [
+            "-e",
+            "json",
+            "-d",
+            "." // the root folder of your project
+          ],
+        },
+        "build-storybook": {
+          ...,
+          "compodoc": true,
+          "compodocArgs": [
+            "-e",
+            "json",
+            "-d",
+            "." // the root folder of your project
+          ],
+        }
+      }
+    }
+  }
 }
 ```
 
 Unfortunately, it's not currently possible to update this dynamically as you edit your components, but [there's an open issue](https://github.com/storybookjs/storybook/issues/8672) to support this with improvements to Compodoc.
 
-Next, add the following to `.storybook/preview.ts` to load the Compodoc-generated file:
-
-```js
-import { setCompodocJson } from '@storybook/addon-docs/angular';
-import docJson from '../documentation.json';
-setCompodocJson(docJson);
-```
-
 Finally, be sure to fill in the `component` field in your story metadata:
 
 ```ts

diff --git a/docs/essentials/auto-generated-controls/angular.mdx b/docs/essentials/auto-generated-controls/angular.mdx
@@ -11,6 +11,12 @@ export default {
 
 Storybook uses this to auto-generate the `ArgTypes` for your component using [Compodoc](https://compodoc.app/). It supports `inputs`, `outputs`, `properties`, `methods`, `view/content child/children` as first class prop types.
 
+## Automatic Compodoc setup
+
+During `sb init`, you will be asked, whether you want to setup Compodoc for your project. Just answer the question with Yes. Compodoc is then ready to use!
+
+## Manual Compodoc setup
+
 You'll need to register Compodoc's `documentation.json` file in `.storybook/preview.ts`:
 
 ```js
@@ -26,16 +32,37 @@ Finally, to set up compodoc, you'll first need to install Compodoc:
 yarn add -D @compodoc/compodoc
 ```
 
-Then you'll need to configure Compodoc to generate a `documentation.json` file. Adding the following snippet to your `package.json` creates a metadata file `./documentation.json` each time you run storybook:
+Then you'll need to configure Compodoc to generate a `documentation.json` file. Adding the following snippet to your `projects.<project>.architect.<storybook|build-storybook>` in the `angular.json` creates a metadata file `./documentation.json` each time you run storybook:
 
-```json
+```jsonc
+// angular.json
 {
-  ...
-  "scripts": {
-    "docs:json": "compodoc -p ./tsconfig.json -e json -d .",
-    "storybook": "npm run docs:json && start-storybook -p 6006 -s src/assets",
-    ...
-  },
+  "projects": {
+    "your-project": {
+      "architect": {
+        "storybook": {
+          ...,
+          "compodoc": true,
+          "compodocArgs": [
+            "-e",
+            "json",
+            "-d",
+            "." // the root folder of your project
+          ],
+        },
+        "build-storybook": {
+          ...,
+          "compodoc": true,
+          "compodocArgs": [
+            "-e",
+            "json",
+            "-d",
+            "." // the root folder of your project
+          ],
+        }
+      }
+    }
+  }
 }
 ```
 

diff --git a/scripts/tasks/sandbox-parts.ts b/scripts/tasks/sandbox-parts.ts
@@ -1,8 +1,16 @@
 // This file requires many imports from `../code`, which requires both an install and bootstrap of
 // the repo to work properly. So we load it async in the task runner *after* those steps.
 
-/* eslint-disable no-restricted-syntax, no-await-in-loop */
-import { copy, ensureSymlink, ensureDir, existsSync, pathExists } from 'fs-extra';
+/* eslint-disable no-restricted-syntax, no-await-in-loop, no-param-reassign */
+import {
+  copy,
+  ensureSymlink,
+  ensureDir,
+  existsSync,
+  pathExists,
+  readJson,
+  writeJson,
+} from 'fs-extra';
 import { join, resolve, sep } from 'path';
 
 import type { Task } from '../task';
@@ -125,6 +133,13 @@ export const install: Task['run'] = async ({ sandboxDir, template }, { link, dry
     prefix:
       'NODE_OPTIONS="--preserve-symlinks --preserve-symlinks-main" STORYBOOK_TELEMETRY_URL="http://localhost:6007/event-log"',
   });
+
+  switch (template.expected.framework) {
+    case '@storybook/angular':
+      await prepareAngularSandbox(cwd);
+      break;
+    default:
+  }
 };
 
 // Ensure that sandboxes can refer to story files defined in `code/`.
@@ -428,3 +443,32 @@ export const addStories: Task['run'] = async (
 
   await writeConfig(mainConfig);
 };
+
+/**
+ * Sets compodoc option in angular.json projects to false. We have to generate compodoc
+ * manually to avoid symlink issues related to the template-stories folder.
+ * In a second step a docs:json script is placed into the package.json to generate the
+ * Compodoc documentation.json, which respects symlinks
+ * */
+async function prepareAngularSandbox(cwd: string) {
+  const angularJson = await readJson(join(cwd, 'angular.json'));
+
+  Object.keys(angularJson.projects).forEach((projectName: string) => {
+    angularJson.projects[projectName].architect.storybook.options.compodoc = false;
+    angularJson.projects[projectName].architect['build-storybook'].options.compodoc = false;
+  });
+
+  await writeJson(join(cwd, 'angular.json'), angularJson, { spaces: 2 });
+
+  const packageJsonPath = join(cwd, 'package.json');
+  const packageJson = await readJson(packageJsonPath);
+
+  packageJson.scripts = {
+    ...packageJson.scripts,
+    'docs:json': 'DIR=$PWD; cd ../../scripts; yarn ts-node combine-compodoc $DIR',
+    storybook: `yarn docs:json && ${packageJson.scripts.storybook}`,
+    'build-storybook': `yarn docs:json && ${packageJson.scripts['build-storybook']}`,
+  };
+
+  await writeJson(packageJsonPath, packageJson, { spaces: 2 });
+}
diff --git a/scripts/utils/package-json.ts b/scripts/utils/package-json.ts
@@ -10,10 +10,6 @@ export async function updatePackageScripts({ cwd, prefix }: { cwd: string; prefi
       storybook: `${prefix} ${packageJson.scripts.storybook}`,
       'build-storybook': `${prefix} ${packageJson.scripts['build-storybook']}`,
     }),
-    // See comment in combine-compodoc as to why this is necessary
-    ...(packageJson.scripts['docs:json'] && {
-      'docs:json': 'DIR=$PWD; cd ../../scripts; yarn ts-node combine-compodoc $DIR',
-    }),
   };
   await writeJSON(packageJsonPath, packageJson, { spaces: 2 });
 }