styleguide.md

Usage

To run the styleguide, use yarn styleguide. The styleguide would be hosted on localhost:6060.

This dev styleguide dev server supports hot reloading, so just save your components and refresh the styleguide page to see your changes.

Adding documentation to components

Each component has 4 areas to be documented:

1 - Component Description

A JSDoc is to be written before the declaration of the component.

/**
 * Write the component's description here.
 */
function MyComponent(props) {
  /* ... */
}

Styleguidist Documentation

2 - Component's Props Description

Write each prop's description before the prop itself. This can be written for both components that use flow-type or propTypes. The type would automatically be fetched and generated by styleguidist.

// PropType Example
MyComponent.propTypes = {
  /**
   * Main text for MyComponent.
   */
  header: PropTypes.string,
  // ...
}

// FlowType Example
type Props = {|
  /**
   * Main text for MyComponent.
   */
  header: string,
  // ...
|}

3 - Component Examples

Create a new .md file in the same folder as the component itself. Everytime a code fence is written in markdown, it would generate a code playground in the code editor, and display the component above it.

Example filename: MyComponent.md

```jsx
import MyComponent from '@b12/metronome/components/path/to/MyComponent.es6.js';

<>
  <MyComponent />
<>
```

Read up on more advanced usage such as react hooks in the playground here.

4 - Styleguide Config File

Add a new entry to components under sections.components every time a new component example is being added.

Folder Directory

This is the recommended way to organize components and examples in the folders.

.
├── ...
├── MyComponent
│   ├── MyComponent.es6.js
│   ├── MyComponent.example.md
│   ├── MySubComponentThatIsUsedByMyComponent
│   │   ├── MySubComponent.es6.js
│   └────── MySubComponent.example.md
├── MyOtherComponentUsingMyComponent
│   ├── MyOtherComponent.es6.js
│   ├── MyOtherComponent.example.md
│   └── ...