docs(storybook): point to targets doc from compodoc (#13024)

docs/generated/packages/storybook.json

@@ -41,7 +41,7 @@
       "id": "angular-storybook-compodoc",
       "name": "Angular: Set up Compodoc for Storybook on Nx",
       "file": "shared/guides/storybook/angular-storybook-compodoc",
-      "content": "# Set up Compodoc for Storybook on Nx\n\n{% callout type=\"note\" title=\"Note\" %}\nThis documentation page contains information about the [Storybook plugin](/packages/storybook), specifically regarding [Angular projects that are using Storybook](/storybook/overview-angular).\n{% /callout %}\n\n{% github-repository url=\"https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular\" /%}\n\n## What is Compodoc\n\n[Compodoc](https://compodoc.app/) is a documentation generator for Angular applications. You can use [JSDoc](https://jsdoc.app/) comment blocks above your components, directives, and other Angular constructs, to add documentation to the elements that you want. These comments are used by `compodoc` to generate documentation for your application. As is noted in the [Compodoc documentation](https://compodoc.app/guides/comments.html), \"Compodoc uses the Typescript AST parser and it's internal APIs, so the comments have to be JSDoc comments\". You can read more about the JSDoc tags that Compodoc supports [here](https://compodoc.app/guides/jsdoc-tags.html).\n\n## How to use Compodoc in Storybook to write documentation\n\nIn Storybook, it makes sense to add explanatory comments above your `@Input`s and `@Output`s, since these are the main elements that Storybook focuses on. The `@Input`s and `@Output`s are the elements that you can interact with in the Storybook UI, the controls.\n\nLet's take for example an Angular component - a button - that has an `@Input` for the size of the button. In Compodoc, we could describe this input as follows:\n\n```ts\n  /**\n   * How large should the button be?\n   */\n  @Input()\n  size: 'small' | 'medium' | 'large' = 'medium';\n```\n\nThis comment would result in the following documentation in Compodoc:\n\n![Button size `@Input` generated documentation](/shared/guides/storybook/button-size-input.png)\n\nIf we add a description and a default value to each of our component `@Input`s, we will end up with a full documentation page. See a full example of the button component [here](https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular/apps/web/src/app/butn/butn.component.ts). The generated documentation of this example will look like this:\n\n![Generated Docs page for the Button](/shared/guides/storybook/button-docs.png)\n\nWhen you run Compodoc, it will generate a `documentation.json` file. Storybook will then use that file to render the documentation in the `Docs` tab.\n\n## How to enable Compodoc for Storybook\n\nThe main things that you need to do are:\n\n1. Include the component files in the TypeScript compilation for Compodoc (or any other files that contain your Compodoc documentation).\n2. Use `compodoc` to generate a `documentation.json` file.\n3. Tell Storybook to use the `documentation.json` file to display the documentation.\n\nLet's see how you can do that.\n\n{% callout type=\"note\" title=\"Note\" %}\nThis guide assumes that you have an Angular project with Storybook configured in your Nx workspace. If you do not know how to set these up, please read about [setting up Storybook for Angular](/storybook/overview-angular) on the Nx documentation website.\n{% /callout %}\n\n### 1. Install the necessary packages\n\nFirst we need to install the necessary packages:\n\n```shell\nyarn add -D @compodoc/compodoc\n```\n\nor\n\n```shell\nnpm install --save-dev @compodoc/compodoc\n```\n\n### 2. Include the component files in the TypeScript compilation for Compodoc\n\nWhen you are using Compodoc, you need to create a `tsconfig` file, and in the `include` array you need to place all the files that you want Compodoc to include in its compilation. Compodoc [suggests](https://compodoc.app/guides/installation.html) to add a `tsconfig.doc.json` to do that. Then, when running `compodoc` you can use the `-p` (or `--tsconfig`) flag to specify the path to that file. See all the options that Compodoc supports [here](https://compodoc.app/guides/options.html).\n\nIn the Storybook case, Storybook has the `--tsconfig` option [prefilled](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L23) to point to the `.storybook/tsconfig.json` file. As is noted in the [Storybook schema for the Angular builders](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/start-storybook/schema.json#L76), \"_Options `-p` with tsconfig path and `-d` with workspace root is always given._\". What this means is that you can add the paths to the component files (where Compodoc will look for JSDoc comment blocks) in the `include` array of the `.storybook/tsconfig.json` file. This is the file that Storybook will use to compile the TypeScript files, and it will also be the file that Compodoc will use to compile the TypeScript files.\n\nIn your project's `.storybook/tsconfig.json` file, in the `include` array, add the path to the component files (eg. `\"../src/**/*.component.ts\"`). For example, if you have an application called `web`, the file `apps/web/.storybook/tsconfig.json` will look like this:\n\n```json {% fileName=\".storybook/tsconfig.json\" %}\n{\n  \"extends\": \"../tsconfig.json\",\n  \"compilerOptions\": {\n    \"emitDecoratorMetadata\": true\n  },\n  \"files\": [\"../src/polyfills.ts\"],\n  \"exclude\": [\"../**/*.spec.ts\"],\n  \"include\": [\"../src/**/*.stories.ts\", \"../src/**/*.component.ts\", \"*.js\"]\n}\n```\n\n{% callout type=\"warning\" title=\"Don't forget all the paths!\" %}\nImportant! If you are importing stories from other places, and you want the docs for these stories to be generated, too, you need to add the paths to the other components in the `include` array, as well!\n\nFor example, if your stories paths look like this:\n\n```\n\"../../../**/**/src/lib/**/*.stories.ts\"\n```\n\nmake sure to also include\n\n```\n\"../../../**/**/src/lib/**/*.component.ts\"\n```\n\nfor the components to be included in the TypeScript compilation as well.\n\nThis applies in cases where, for example, you have [one single Storybook for your whole workspace](/recipes/storybook/one-storybook-for-all), where you import stories from all the projects. In that case, you need to import all the components as well!\n{% /callout %}\n\n### 3. Enable `compodoc` and configure it\n\n#### a. Set `compodoc: true`\n\nIn your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets.\n\nIn the `options` you will see `\"compodoc\": false`. Change that to `true`.\n\n#### b. Set the directory\n\nStorybook has [preconfigured `compodoc`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L25) to generate a `documentation.json` file at the root of your workspace by default. We want to change that, and keep the documentation file project-specific. Of course you can change that later, or as you see fit for your use case. But let's keep it project-specific for now.\n\nIn your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets. Below the `\"compodoc\"` option, create a new option called `\"compodocArgs` which contains the following: `[\"-e\", \"json\", \"-d\", \"apps/web\"]`. This means that the `exportFormat` (`-e`) will be `json` and the `output` directory (`-d`) will be `apps/web` (change that, of course, to the directory of your project).\n\nLet's see the result for our `web` app `storybook` target, for example (in `apps/web/project.json`):\n\n```jsonc {% fileName=\"project.json\" %}\n    \"storybook\": {\n      \"executor\": \"@storybook/angular:start-storybook\",\n      \"options\": {\n        \"port\": 4400,\n        \"configDir\": \"apps/web/.storybook\",\n        \"browserTarget\": \"web:build\",\n        \"compodoc\": true,\n        \"compodocArgs\": [\"-e\", \"json\", \"-d\", \"apps/web\"]\n      },\n    },\n```\n\n### 4. Let Storybook know of the `documentation.json` file\n\nIn your project's `.storybook/preview.js` file (for example for your `web` app the path would be `apps/web/.storybook/preview.js`), add the following:\n\n```js {% fileName=\".storybook/preview.js\" %}\nimport { setCompodocJson } from '@storybook/addon-docs/angular';\nimport docJson from '../documentation.json';\nsetCompodocJson(docJson);\n```\n\n### Now run Storybook and see the results!\n\nNow you can run Storybook or build Storybook, and documentation will be included. Just check the Docs tab!\n\n```shell\nnx storybook web\n```\n\nand\n\n```shell\nnx build-storybook web\n```\n"
+      "content": "# Set up Compodoc for Storybook on Nx\n\n{% callout type=\"note\" title=\"Note\" %}\nThis documentation page contains information about the [Storybook plugin](/packages/storybook), specifically regarding [Angular projects that are using Storybook](/storybook/overview-angular).\n{% /callout %}\n\n{% github-repository url=\"https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular\" /%}\n\n## What is Compodoc\n\n[Compodoc](https://compodoc.app/) is a documentation generator for Angular applications. You can use [JSDoc](https://jsdoc.app/) comment blocks above your components, directives, and other Angular constructs, to add documentation to the elements that you want. These comments are used by `compodoc` to generate documentation for your application. As is noted in the [Compodoc documentation](https://compodoc.app/guides/comments.html), \"Compodoc uses the Typescript AST parser and it's internal APIs, so the comments have to be JSDoc comments\". You can read more about the JSDoc tags that Compodoc supports [here](https://compodoc.app/guides/jsdoc-tags.html).\n\n## How to use Compodoc in Storybook to write documentation\n\nIn Storybook, it makes sense to add explanatory comments above your `@Input`s and `@Output`s, since these are the main elements that Storybook focuses on. The `@Input`s and `@Output`s are the elements that you can interact with in the Storybook UI, the controls.\n\nLet's take for example an Angular component - a button - that has an `@Input` for the size of the button. In Compodoc, we could describe this input as follows:\n\n```ts\n  /**\n   * How large should the button be?\n   */\n  @Input()\n  size: 'small' | 'medium' | 'large' = 'medium';\n```\n\nThis comment would result in the following documentation in Compodoc:\n\n![Button size `@Input` generated documentation](/shared/guides/storybook/button-size-input.png)\n\nIf we add a description and a default value to each of our component `@Input`s, we will end up with a full documentation page. See a full example of the button component [here](https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular/apps/web/src/app/butn/butn.component.ts). The generated documentation of this example will look like this:\n\n![Generated Docs page for the Button](/shared/guides/storybook/button-docs.png)\n\nWhen you run Compodoc, it will generate a `documentation.json` file. Storybook will then use that file to render the documentation in the `Docs` tab.\n\n## How to enable Compodoc for Storybook\n\nThe main things that you need to do are:\n\n1. Include the component files in the TypeScript compilation for Compodoc (or any other files that contain your Compodoc documentation).\n2. Use `compodoc` to generate a `documentation.json` file.\n3. Tell Storybook to use the `documentation.json` file to display the documentation.\n\nLet's see how you can do that.\n\n{% callout type=\"note\" title=\"Note\" %}\nThis guide assumes that you have an Angular project with Storybook configured in your Nx workspace. If you do not know how to set these up, please read about [setting up Storybook for Angular](/storybook/overview-angular) on the Nx documentation website.\n{% /callout %}\n\n### 1. Install the necessary packages\n\nFirst we need to install the necessary packages:\n\n```shell\nyarn add -D @compodoc/compodoc\n```\n\nor\n\n```shell\nnpm install --save-dev @compodoc/compodoc\n```\n\n### 2. Include the component files in the TypeScript compilation for Compodoc\n\nWhen you are using Compodoc, you need to create a `tsconfig` file, and in the `include` array you need to place all the files that you want Compodoc to include in its compilation. Compodoc [suggests](https://compodoc.app/guides/installation.html) to add a `tsconfig.doc.json` to do that. Then, when running `compodoc` you can use the `-p` (or `--tsconfig`) flag to specify the path to that file. See all the options that Compodoc supports [here](https://compodoc.app/guides/options.html).\n\nIn the Storybook case, Storybook has the `--tsconfig` option [prefilled](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L23) to point to the `.storybook/tsconfig.json` file. As is noted in the [Storybook schema for the Angular builders](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/start-storybook/schema.json#L76), \"_Options `-p` with tsconfig path and `-d` with workspace root is always given._\". What this means is that you can add the paths to the component files (where Compodoc will look for JSDoc comment blocks) in the `include` array of the `.storybook/tsconfig.json` file. This is the file that Storybook will use to compile the TypeScript files, and it will also be the file that Compodoc will use to compile the TypeScript files.\n\nIn your project's `.storybook/tsconfig.json` file, in the `include` array, add the path to the component files (eg. `\"../src/**/*.component.ts\"`). For example, if you have an application called `web`, the file `apps/web/.storybook/tsconfig.json` will look like this:\n\n```json {% fileName=\".storybook/tsconfig.json\" %}\n{\n  \"extends\": \"../tsconfig.json\",\n  \"compilerOptions\": {\n    \"emitDecoratorMetadata\": true\n  },\n  \"files\": [\"../src/polyfills.ts\"],\n  \"exclude\": [\"../**/*.spec.ts\"],\n  \"include\": [\"../src/**/*.stories.ts\", \"../src/**/*.component.ts\", \"*.js\"]\n}\n```\n\n{% callout type=\"warning\" title=\"Don't forget all the paths!\" %}\nImportant! If you are importing stories from other places, and you want the docs for these stories to be generated, too, you need to add the paths to the other components in the `include` array, as well!\n\nFor example, if your stories paths look like this:\n\n```\n\"../../../**/**/src/lib/**/*.stories.ts\"\n```\n\nmake sure to also include\n\n```\n\"../../../**/**/src/lib/**/*.component.ts\"\n```\n\nfor the components to be included in the TypeScript compilation as well.\n\nThis applies in cases where, for example, you have [one single Storybook for your whole workspace](/recipes/storybook/one-storybook-for-all), where you import stories from all the projects. In that case, you need to import all the components as well!\n{% /callout %}\n\n### 3. Enable `compodoc` and configure it\n\n#### a. Set `compodoc: true`\n\nIn your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets.\n\nIn the `options` you will see `\"compodoc\": false`. Change that to `true`.\n\n#### b. Set the directory\n\nStorybook has [preconfigured `compodoc`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L25) to generate a `documentation.json` file at the root of your workspace by default. We want to change that, and keep the documentation file project-specific. Of course you can change that later, or as you see fit for your use case. But let's keep it project-specific for now.\n\nIn your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets. Below the `\"compodoc\"` option, create a new option called `\"compodocArgs` which contains the following: `[\"-e\", \"json\", \"-d\", \"apps/web\"]`. This means that the `exportFormat` (`-e`) will be `json` and the `output` directory (`-d`) will be `apps/web` (change that, of course, to the directory of your project).\n\nLet's see the result for our `web` app `storybook` target, for example (in `apps/web/project.json`):\n\n```jsonc {% fileName=\"project.json\" %}\n    \"storybook\": {\n      \"executor\": \"@storybook/angular:start-storybook\",\n      \"options\": {\n        \"port\": 4400,\n        \"configDir\": \"apps/web/.storybook\",\n        \"browserTarget\": \"web:build\",\n        \"compodoc\": true,\n        \"compodocArgs\": [\"-e\", \"json\", \"-d\", \"apps/web\"]\n      },\n    },\n```\n\n{% callout type=\"warning\" title=\"Check the version!\" %}\nMake sure you are on Nx version `>=14.1.8` and your `storybook` target is using `@storybook/angular:start-storybook` as the `executor` (like the example above).\n\nIf you are using an older version of Nx, you can use [`nx migrate`](/nx/migrate) to migrate your codebase to a later version. Using `nx migrate` will also make sure to update your `storybook` and `build-storybook` targets to match the new format.\n\nIf you **are** on Nx `>=14.1.8` and you are still using the old executor (`@nrwl/storybook:storybook`), you can use the [`change-storybook-targets` generator](/packages/storybook/generators/change-storybook-targets) which will take care of changing your `storybook` and `build-storybook` targets across your workspace for your Angular projects using Storybook.\n\nYou can read more about the `storybook` and `build-storybook` targets for Angular projects in the [Information about the `storybook` targets](/storybook/angular-storybook-targets) page.\n{% /callout %}\n\n### 4. Let Storybook know of the `documentation.json` file\n\nIn your project's `.storybook/preview.js` file (for example for your `web` app the path would be `apps/web/.storybook/preview.js`), add the following:\n\n```js {% fileName=\".storybook/preview.js\" %}\nimport { setCompodocJson } from '@storybook/addon-docs/angular';\nimport docJson from '../documentation.json';\nsetCompodocJson(docJson);\n```\n\n### Now run Storybook and see the results!\n\nNow you can run Storybook or build Storybook, and documentation will be included. Just check the Docs tab!\n\n```shell\nnx storybook web\n```\n\nand\n\n```shell\nnx build-storybook web\n```\n"
     },
     {
       "id": "angular-storybook-targets",
@@ -260,6 +260,7 @@
         "type": "object",
         "properties": {},
         "required": [],
+        "examplesFile": "This generator will change the `storybook` and `build-storybook` targets in all your Angular projects that are configured to use Storybook. The new target configuration will use the native Storybook builders (`@storybook/angular:build-storybook` and `@storybook/angular:start-storybook`) instead of the Nx Storybook builders (`@nrwl/storybook:build-storybook` and `@nrwl/storybook:storybook`).\n\nThis generator is usually invoked through a migrator, when you are using `nx migrate` to upgrade your workspace to Nx `14.1.8` or later.\n\nIf you are on Nx `14.1.8` or later and you did not use `nx migrate`, you can run this generator manually by running the following command:\n\n```bash\nnx g @nrwl/storybook:change-storybook-targets\n```\n\nYou can read more about how this generator works, and why we are changing the Storybook targets, in the [Angular Storybook targets documentation page](/storybook/angular-storybook-targets).\n",
         "presets": []
       },
       "description": "Change storybook targets for Angular projects to use @storybook/angular executors",