miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs(storybook): update and fix some parts of recipes (#19578)

Browse Source
This commit is contained in:
Katerina Skroumpelou 2023-10-12 16:40:59 +03:00 committed by GitHub
parent f83cf0162f
commit c231c9e6eb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 54 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/shared/recipes/storybook/angular-storybook-compodoc.md
View File

@ -33,7 +33,7 @@ This comment would result in the following documentation in Compodoc:
![Button size `@Input` generated documentation](/shared/recipes/storybook/button-size-input.png) ![Button size `@Input` generated documentation](/shared/recipes/storybook/button-size-input.png)
If 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: If 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/my-app/src/app/butn/butn.component.ts). The generated documentation of this example will look like this:
![Generated Docs page for the Button](/shared/recipes/storybook/button-docs.png) ![Generated Docs page for the Button](/shared/recipes/storybook/button-docs.png)
@ -59,29 +59,44 @@ This guide assumes that you have an Angular project with Storybook configured in
First we need to install the necessary packages: First we need to install the necessary packages:
{% tabs %}
{% tab label="yarn" %}
```shell ```shell
yarn add -D @compodoc/compodoc yarn add -D @compodoc/compodoc
``` ```
or {% /tab %}
{% tab label="npm" %}
```shell ```shell
npm install --save-dev @compodoc/compodoc npm install --save-dev @compodoc/compodoc
``` ```
{% /tab %}
{% tab label="pnpm" %}
```shell
pnpm install --save-dev @compodoc/compodoc
```
{% /tab %}
{% /tabs %}
### 2. Include the component files in the TypeScript compilation for Compodoc ### 2. Include the component files in the TypeScript compilation for Compodoc
When 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). When 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).
In 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. In 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.
In 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: In 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 `my-app`, the file `apps/my-app/.storybook/tsconfig.json` will look like this:
```json {% fileName="apps/web/.storybook/tsconfig.json" %} ```json {% fileName="apps/my-app/.storybook/tsconfig.json" %}
{ {
"extends": "../tsconfig.json", "extends": "../tsconfig.json",
"compilerOptions": { "compilerOptions": {
"emitDecoratorMetadata": true "emitDecoratorMetadata": true,
"resolveJsonModule": true
}, },
"files": ["../src/polyfills.ts"], "files": ["../src/polyfills.ts"],
"exclude": ["../**/*.spec.ts"], "exclude": ["../**/*.spec.ts"],
@ -113,7 +128,7 @@ This applies in cases where, for example, you have [one single Storybook for you
#### a. Set `compodoc: true` #### a. Set `compodoc: true`
In your project's `project.json` file (e.g. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets. In your project's `project.json` file (e.g. `apps/my-app/project.json`), find the `storybook` and the `build-storybook` targets.
In the `options` you will see `"compodoc": false`. Change that to `true`. In the `options` you will see `"compodoc": false`. Change that to `true`.
@ -121,38 +136,53 @@ In the `options` you will see `"compodoc": false`. Change that to `true`.
Storybook 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. Storybook 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.
In 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). In your project's `project.json` file (eg. `apps/my-app/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/my-app"]`. This means that the `exportFormat` (`-e`) will be `json` and the `output` directory (`-d`) will be `apps/my-app` (change that, of course, to the directory of your project).
Let's see the result for our `web` app `storybook` target, for example (in `apps/web/project.json`): Let's see the result for our `my-app` app `storybook` target, for example (in `apps/my-app/project.json`):
```jsonc {% fileName="project.json" %} ```jsonc {% fileName="apps/my-app/project.json" %}
"storybook": { "storybook": {
"executor": "@storybook/angular:start-storybook", "executor": "@storybook/angular:start-storybook",
"options": { "options": {
"port": 4400, "port": 4400,
"configDir": "apps/web/.storybook", "configDir": "apps/my-app/.storybook",
"browserTarget": "web:build", "browserTarget": "my-app:build",
"compodoc": true, "compodoc": true,
"compodocArgs": ["-e", "json", "-d", "apps/web"] "compodocArgs": ["-e", "json", "-d", "apps/my-app"]
}, },
}, },
``` ```
### 4. Let Storybook know of the `documentation.json` file ### 4. Let Storybook know of the `documentation.json` file
In 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: In your project's `.storybook/preview.ts` file (for example for your `my-app` app the path would be `apps/my-app/.storybook/preview.ts`), add the following:
```js {% fileName="apps/web/.storybook/preview.js" %} ```js {% fileName="apps/my-app/.storybook/preview.ts" %}
import { setCompodocJson } from '@storybook/addon-docs/angular'; import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json'; import docJson from '../documentation.json';
setCompodocJson(docJson); setCompodocJson(docJson);
``` ```
Notice how we are adding `"resolveJsonModule": true` in our app's `.storybook/tsconfig.json` in order to be able to import the `documentation.json` file:
```json {% fileName="apps/my-app/.storybook/tsconfig.json" %}
{
"extends": "../tsconfig.json",
"compilerOptions": {
"emitDecoratorMetadata": true,
"resolveJsonModule": true
},
"files": ["../src/polyfills.ts"],
"exclude": ["../**/*.spec.ts"],
"include": ["../src/**/*.stories.ts", "../src/**/*.component.ts", "*.js"]
}
```
### 5. Set up Autodocs ### 5. Set up Autodocs
In your project's `.storybook/main.js` file you have to enable autodocs: In your project's `.storybook/main.ts` file you have to enable autodocs:
```js {% fileName="apps/web/.storybook/main.js" %} ```js {% fileName="apps/my-app/.storybook/main.ts" %}
const config = { const config = {
stories: ['../src/app/**/*.stories.@(js|jsx|ts|tsx|mdx)'], stories: ['../src/app/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
addons: ['@storybook/addon-essentials'], addons: ['@storybook/addon-essentials'],
@ -169,16 +199,16 @@ const config = {
export default config; export default config;
``` ```
### Now run Storybook and see the results! ### Now run Storybook and see the results
Now you can run Storybook or build Storybook, and documentation will be included. Just check the Docs tab! Now you can run Storybook or build Storybook, and documentation will be included. Just check the Docs tab!
```shell ```shell
nx storybook web nx storybook my-app
``` ```
and and
```shell ```shell
nx build-storybook web nx build-storybook my-app
``` ```

22
docs/shared/recipes/storybook/one-storybook-for-all.md
View File

@ -80,35 +80,23 @@ stories: [
]; ];
``` ```
### Import the stories in tsconfig.storybook.json ### If you're using Angular add the stories in your tsconfig.json
Here is a sample `libs/storybook-host/tsconfig.storybook.json` file: Here is a sample `libs/storybook-host/.storybook/tsconfig.json` file:
```json {% fileName="libs/storybook-host/tsconfig.storybook.json" %} ```json {% fileName="libs/storybook-host/.storybook/tsconfig.json" %}
{ {
"extends": "../tsconfig.json", "extends": "../tsconfig.json",
"compilerOptions": { "compilerOptions": {
"emitDecoratorMetadata": true "emitDecoratorMetadata": true
}, },
... "exclude": ["../**/*.spec.ts"],
"include": [ "include": ["../../**/ui/**/src/lib/**/*.stories.ts", "*.ts"]
"../../**/ui/**/src/**/*.stories.ts",
"../../**/ui/**/src/**/*.stories.js",
"../../**/ui/**/src/**/*.stories.jsx",
"../../**/ui/**/src/**/*.stories.tsx",
"../../**/ui/**/src/**/*.stories.mdx",
".storybook/*.js",
".storybook/*.ts"
]
} }
``` ```
Notice how in the `include` array we are specifying the paths to our stories, using the same pattern we used in our `.storybook/main.ts`. Notice how in the `include` array we are specifying the paths to our stories, using the same pattern we used in our `.storybook/main.ts`.
{% callout type="note" title="Angular Storybook tsconfig.json" %}
For Angular, that file is in your project's `.storybook` directory, so in this case it would be under `libs/storybook-host/.storybook/tsconfig.json`.
{% /callout %}
### Serve or build your Storybook ### Serve or build your Storybook
Now you can serve, test or build your Storybook as you would, normally. And then you can publish the bundled app! Now you can serve, test or build your Storybook as you would, normally. And then you can publish the bundled app!