Addon-docs: Angular docs readme

addons/docs/README.md

@@ -18,6 +18,7 @@ Read on to learn more:
 - [MDX](#mdx)
 - [Framework support](#framework-support)
 - [Installation](#installation)
+  - [Be sure to check framework specific installation needs](#be-sure-to-check-framework-specific-installation-needs)
 - [Preset options](#preset-options)
 - [Manual configuration](#manual-configuration)
 - [TypeScript configuration](#typescript-configuration)
@@ -138,6 +139,7 @@ Add the following to your Jest configuration:
 
 ### Be sure to check framework specific installation needs
 
+- [Angular](./angular)
 - [Web Components](./web-components)
 
 ## Preset options
@@ -234,4 +236,3 @@ Want to learn more? Here are some more articles on Storybook Docs:
 - Vision: [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
 - Announcement: [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf)
 - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
-- [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)

addons/docs/angular/README.md

@@ -0,0 +1,164 @@
+<center>
+  <img src="../docs/media/angular-hero.png" width="100%" />
+</center>
+
+# Storybook Docs for Angular
+
+Storybook Docs transforms your Storybook stories into world-class component documentation. Storybook Docs for Angular supports [DocsPage](../docs/docspage.md) for auto-generated docs, and [MDX](../docs/mdx.md) for rich long-form docs.
+
+To learn more about Storybook Docs, read the [general documentation](../README.md). To learn the Angular specifics, read on!
+
+- [Installation](#installation)
+- [DocsPage](#docspage)
+- [MDX](#mdx)
+- [IFrame height](#iframe-height)
+- [More resources](#more-resources)
+
+## Installation
+
+First add the package. Make sure that the versions for your `@storybook/*` packages match:
+
+```sh
+yarn add -D @storybook/addon-docs@next
+```
+
+Then add the following to your `.storybook/presets.js` exports:
+
+```js
+module.exports = ['@storybook/addon-docs/angular/preset'];
+```
+
+## DocsPage
+
+When you [install docs](#installation) you should get basic [DocsPage](../docs/docspage.md) documentation automagically for all your Angular stories, available in the `Docs` tab of the Storybook UI.
+
+Pops tables 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:
+
+```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:
+
+```json
+{
+  ...
+  "scripts": {
+    "docs:json": "compodoc -p ./tsconfig.json -e json -d .",
+    "storybook": "npm run docs:json && start-storybook -p 9008 -s src/assets",
+    ...
+  },
+}
+```
+
+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 your `.storybook/config.json` 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
+import { AppComponent } from './app.component';
+
+export default {
+  title: 'App Component',
+  component: AppComponent,
+};
+```
+
+If you haven't upgraded from `storiesOf`, you can use a parameter to do the same thing:
+
+```ts
+import { storiesOf } from '@storybook/angular';
+import { AppComponent } from './app.component';
+
+storiesOf('App Component', module)
+  .addParameters({ component: AppComponent })
+  .add( ... );
+```
+
+## MDX
+
+[MDX](../docs/mdx.md) is a convenient way to document your components in Markdown and embed documentation components, such as stories and props tables, inline.
+
+Docs has peer dependencies on `react`, `react-is`, and `babel-loader`. If you want to write stories in MDX, you'll need to add these dependencies as well:
+
+```sh
+yarn add -D react react-is babel-loader
+```
+
+Then update your `.storybook/config.ts` to make sure you load MDX files:
+
+```ts
+configure(require.context('../src/stories', true, /\.stories\.(ts|mdx)$/), module);
+```
+
+Finally, you can create MDX files like this:
+
+```md
+import { Meta, Story, Props } from '@storybook/docs/blocks';
+import { AppComponent } from './app.component';
+
+<Meta title="'App Component" component={AppComponent} />
+
+# App Component
+
+Some **markdown** description, or whatever you want.
+
+<Story name='basic' height='400px'>{{
+  component: AppComponent,
+  props: {},
+}}</Story>
+
+## Props
+
+<Props of={AppComponent} />
+```
+
+Yes, it's redundant to declare `component` twice. [Coming soon](https://github.com/storybookjs/storybook/issues/8673).
+
+Also, to use the `Props` doc block, you need to set up Compodoc, [as described above](#docspage).
+
+## IFrame height
+
+Storybook Docs renders all Angular stories inside IFrames, with a default height of `60px`. You can update this default globally, or modify the IFrame height locally per story in `DocsPage` and `MDX`.
+
+To update the global default, modify `.storybook/config.ts`:
+
+```ts
+import { addParameters } from '@storybook/angular';
+
+addParameters({ docs: { iframeHeight: 400 } });
+```
+
+For `DocsPage`, you need to update the parameter locally in a story:
+
+```ts
+export const basic = () => ...
+basic.story = {
+  parameters: { docs: { iframeHeight: 400 } }
+}
+```
+
+And for `MDX` you can modify it as an attribute on the `Story` element:
+
+```md
+<Story name='basic' height='400px'>{...}</Story>
+```
+
+## More resources
+
+Want to learn more? Here are some more articles on Storybook Docs:
+
+- References: [DocsPage](../docs/docspage.md) / [MDX](../docs/mdx.md) / [FAQ](../docs/faq.md) / [Recipes](../docs/recipes.md) / [Theming](../docs/theming.md)
+- Vision: [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
+- Announcement: [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf)
+- Example: [Storybook Design System](https://github.com/storybookjs/design-system)

addons/docs/src/frameworks/angular/compodoc.ts

@@ -106,7 +106,7 @@ export const extractProps = (component: Component) => {
         name: item.name,
         type: { name: isMethod(item) ? displaySignature(item) : item.type },
         required: isMethod(item) ? false : !item.optional,
-        description: isMethod(item) ? item.description : '',
+        description: item.description,
         defaultValue: isMethod(item) ? '' : item.defaultValue,
       };
 

addons/docs/src/frameworks/angular/types.ts

@@ -12,6 +12,7 @@ export interface Property {
   type: string;
   optional: boolean;
   defaultValue?: string;
+  description?: string;
 }
 
 export interface Component {

examples/angular-cli/src/stories/doc-button/__snapshots__/doc-button.stories.storyshot

@@ -11,7 +11,12 @@ exports[`Storyshots DocButton Basic 1`] = `
       class="btn-secondary btn-medium"
       ng-reflect-ng-class="btn-secondary,btn-medium"
     >
-      Test labels
+      <img
+        src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOS4xLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHZpZXdCb3g9IjAgMCAyNTAgMjUwIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCAyNTAgMjUwOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+DQo8c3R5bGUgdHlwZT0idGV4dC9jc3MiPg0KCS5zdDB7ZmlsbDojREQwMDMxO30NCgkuc3Qxe2ZpbGw6I0MzMDAyRjt9DQoJLnN0MntmaWxsOiNGRkZGRkY7fQ0KPC9zdHlsZT4NCjxnPg0KCTxwb2x5Z29uIGNsYXNzPSJzdDAiIHBvaW50cz0iMTI1LDMwIDEyNSwzMCAxMjUsMzAgMzEuOSw2My4yIDQ2LjEsMTg2LjMgMTI1LDIzMCAxMjUsMjMwIDEyNSwyMzAgMjAzLjksMTg2LjMgMjE4LjEsNjMuMiAJIi8+DQoJPHBvbHlnb24gY2xhc3M9InN0MSIgcG9pbnRzPSIxMjUsMzAgMTI1LDUyLjIgMTI1LDUyLjEgMTI1LDE1My40IDEyNSwxNTMuNCAxMjUsMjMwIDEyNSwyMzAgMjAzLjksMTg2LjMgMjE4LjEsNjMuMiAxMjUsMzAgCSIvPg0KCTxwYXRoIGNsYXNzPSJzdDIiIGQ9Ik0xMjUsNTIuMUw2Ni44LDE4Mi42aDBoMjEuN2gwbDExLjctMjkuMmg0OS40bDExLjcsMjkuMmgwaDIxLjdoMEwxMjUsNTIuMUwxMjUsNTIuMUwxMjUsNTIuMUwxMjUsNTIuMQ0KCQlMMTI1LDUyLjF6IE0xNDIsMTM1LjRIMTA4bDE3LTQwLjlMMTQyLDEzNS40eiIvPg0KPC9nPg0KPC9zdmc+DQo="
+        width="100"
+      />
+       Docs Test
+
     </button>
   </my-button>
 </storybook-dynamic-app-root>

examples/angular-cli/src/stories/doc-button/doc-button.component.html

@@ -1 +1,7 @@
-<button [ngClass]="classes" #buttonRef>{{ label }}</button>
+<button [ngClass]="classes" #buttonRef>
+  <img
+    width="100"
+    src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOS4xLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHZpZXdCb3g9IjAgMCAyNTAgMjUwIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCAyNTAgMjUwOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+DQo8c3R5bGUgdHlwZT0idGV4dC9jc3MiPg0KCS5zdDB7ZmlsbDojREQwMDMxO30NCgkuc3Qxe2ZpbGw6I0MzMDAyRjt9DQoJLnN0MntmaWxsOiNGRkZGRkY7fQ0KPC9zdHlsZT4NCjxnPg0KCTxwb2x5Z29uIGNsYXNzPSJzdDAiIHBvaW50cz0iMTI1LDMwIDEyNSwzMCAxMjUsMzAgMzEuOSw2My4yIDQ2LjEsMTg2LjMgMTI1LDIzMCAxMjUsMjMwIDEyNSwyMzAgMjAzLjksMTg2LjMgMjE4LjEsNjMuMiAJIi8+DQoJPHBvbHlnb24gY2xhc3M9InN0MSIgcG9pbnRzPSIxMjUsMzAgMTI1LDUyLjIgMTI1LDUyLjEgMTI1LDE1My40IDEyNSwxNTMuNCAxMjUsMjMwIDEyNSwyMzAgMjAzLjksMTg2LjMgMjE4LjEsNjMuMiAxMjUsMzAgCSIvPg0KCTxwYXRoIGNsYXNzPSJzdDIiIGQ9Ik0xMjUsNTIuMUw2Ni44LDE4Mi42aDBoMjEuN2gwbDExLjctMjkuMmg0OS40bDExLjcsMjkuMmgwaDIxLjdoMEwxMjUsNTIuMUwxMjUsNTIuMUwxMjUsNTIuMUwxMjUsNTIuMQ0KCQlMMTI1LDUyLjF6IE0xNDIsMTM1LjRIMTA4bDE3LTQwLjlMMTQyLDEzNS40eiIvPg0KPC9nPg0KPC9zdmc+DQo="
+  />
+  {{ label }}
+</button>

examples/angular-cli/src/stories/doc-button/doc-button.component.ts

@@ -22,17 +22,12 @@ export interface ISomeInterface {
 }
 
 /**
- * Short description about the component.
+ * This is a simple button that demonstrates various JSDoc handling in Storybook Docs for Angular.
  *
- * Long description about the component - this also supports [markdown](https://en.wikipedia.org/wiki/Markdown)!
+ * It supports [markdown](https://en.wikipedia.org/wiki/Markdown), so you can embed formatted text,
+ * like **bold**, _italic_, and `inline code`.
  *
- * **Lorem ipsum dolor sit amet**, consectetur adipiscing elit. Nullam sit amet lectus condimentum, _posuere velit id,
- * ornare risus_. In vitae ex eu lacus hendrerit elementum non ut massa. ~~Orci varius natoque penatibus et magnis dis
- * parturient montes~~, nascetur ridiculus mus. `Nullam vehicula lacus felis, ac aliquam nisl malesuada ac`.
- *
- * > Cras varius aliquam tortor in efficitur. Proin in egestas libero, ac ullamcoer est.
- *
- * <abbr title="Hypertext Markup Language">HTML</abbr> tags work just as they would in markup.
+ * > How you like dem apples?! It's never been easier to document all your components.
  *
  * @string Hello world
  * @link [Example](http://example.com)

examples/angular-cli/src/stories/doc-button/doc-button.stories.ts

@@ -3,11 +3,12 @@ import { ButtonComponent } from './doc-button.component';
 export default {
   title: 'DocButton',
   component: ButtonComponent,
+  parameters: { docs: { iframeHeight: 120 } },
 };
 
 export const basic = () => ({
   component: ButtonComponent,
   props: {
-    label: 'Test labels',
+    label: 'Docs Test',
   },
 });