Skip to content
This repository has been archived by the owner. It is now read-only.
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
app
 
 
bin
 
 
 
 
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

React Styleguide Generator

CircleCI npm Join the chat at https://gitter.im/pocotan001/react-styleguide-generator

Easily generate a good-looking styleguide by adding some documentation to your React project.

preview
Demo using the React-Bootstrap.

Installation

npm install react-styleguide-generator

Which requires React 15.x.x or newer. To install it npm install react.

Quick Start

NOTE: By default Babel's static keyword is disabled. You can turn them on individually by passing stage 0 as a babelrc or options.babelConfig.

Documenting your React components

Create file for the styleguide, and then add some documentation to a static field named styleguide. You can use the ES6 syntax by Babel.

import React from 'react'
import Button from './Button'

export default class extends React.Component {
  static styleguide = {
    index: '1.1',
    category: 'Elements',
    title: 'Button',
    description: 'You can use **Markdown** within this `description` field.',
    code: `<Button size='small|large' onClick={Function}>Cool Button</Button>`,
    className: 'apply the css class'
  }

  onClick () {
    alert('Alo!')
  }

  render () {
    return (
      <Button size='large' onClick={this.onClick}>Cool Button</Button>
    )
  }
}
  • index: Reference to the element's position in the styleguide (optional)
  • category: Components category name
  • title: Components title
  • description: Components description (optional)
  • code: Code example (optional). Not specifying this will not auto-generate an example.
  • className: CSS class name (optional)

Additional examples in tabs (optional) Demo

You can optionally use tabs to segment out examples for a component:

import React from 'react'
import Button from './Button'

export default class extends React.Component {
  static styleguide = {
    
    // Component to use for generating additional examples
    exampleComponent: Button,
    // Array of additional example tabs
    examples: [{
      tabTitle: 'Default',
      props: {
        children: 'Default'
      }
    }, {
      tabTitle: 'Primary',
      props: {
        kind: 'primary',
        children: 'Primary',
        onClick () {
          alert('o hay!')
        }
      }
    }]
  }
}
  • exampleComponent: ReactElement to use to generate the examples.
  • examples: Array of examples, which generates additional tabs of example components and sample code
  • examples[].tabTitle: Title of example tab
  • examples[].props: Properties to assign to the rendered example component
  • examples[].props.children: (optional) Child elements to assign to the example component
  • examples[].code: (optional) Code example. Omitting this will attempt to auto-generate a code example using the examples[].props

Additional examples via doc comment (optional) Demo

Doc comment support example is:

/**
 * Substitute this description for `styleguide.description`.
 */
export default class extends Component {
  // required for prop documentation
  static displayName = 'ExampleButton'

  static styleguide = {}

  // Document the props via react-docgen
  static propTypes = {
    /**
     * Block level
     */
    block: React.PropTypes.bool,
    /**
     * Style types
     */
    kind: React.PropTypes.oneOf(['default', 'primary', 'success', 'info'])
  }

  render () {
    return <Button block kind='primary'>Cool Button</Button>
  }
}

If necessary, visit react-styleguide-generator/example to see more complete examples for the documenting syntax.

Generating the documentation

Command line tool

A common usage example is below.

# The default output to `styleguide` directory
rsg 'example/**/*.js'

Type rsg -h or rsg --help to get all the available options.

Usage: rsg [input] [options]

Options:
  -o, --output     Output directory            ['styleguide']
  -t, --title      Used as a page title        ['Style Guide']
  -r, --root       Set the root path           ['.']
  -f, --files      Inject references to files  ['']
  -c, --config     Use the config file         ['styleguide.json']
  -p, --pushstate  Enable HTML5 pushState      [false]
  -v, --verbose    Verbose output              [false]
  -w, --watch      Watch mode using `browserifyConfig`

Examples:
  rsg 'example/**/*.js' -t 'Great Style Guide' -f 'a.css, a.js' -v

  # Necessary to use a config file if you want to enable react-docgen
  rsg 'example/**/*.js' -c 'styleguide.json' -v

Gulp

const gulp = require('gulp')
const rsg = require('react-styleguide-generator').rsg

gulp.task('styleguide', function (done) {
  rsg('example/**/*.js', {
    output: 'path/to/dir',
    files: ['a.css', 'a.js']
  }).generate()
    .then(() => done())
    .catch(err => {
      console.error(err)
      done()
    })
})

Grunt

const rsg = require('react-styleguide-generator').rsg

grunt.registerTask('rsg', 'React style guide', function () {
  const done = this.async()

  try {
    const conf = grunt.config.get('rsg')

    rsg(conf.input, {
      config: conf.configFile,
      watch: false,
      verbose: true
    }).generate()
      .then(() => {
        grunt.log.ok('react styleguide generation complete')
        done()
      })
      .catch(err => {
        grunt.log.error('Error: ' + err + ' ' + err.stack())
        done(false)
      })
  } catch (e) {
    grunt.log.error('Error: ' + e + ' ' + e.stack)
    done(false)
  }
})

API

RSG(input, [options])

Returns a new RSG instance.

input

Type: String

Refers to glob syntax or it can be a direct file path.

options

output

Type: String
Default: 'styleguide'

Output directory path.

title

Type: String
Default: 'Style Guide'

Used as a page title and in the page header.

reactDocgen.files

Type: Array Default: input

An array of glob-able file/paths for react-docgen to parse. If not specified, will default the value to input.

root

Type: String
Default: '.'

Set the root path. For example, if the styleguide is hosted at http://example.com/styleguide the options.root should be styleguide.

files

Type: Array
Default: null

Inject references to files. A usage example is:

{
  files: [
    '//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css',
    'a.css',
    'a.js',
    'icon.svg'
  ]
}

Check for the existence of the files and only copy the files if it exists.

styleguide/files
├─ a.css
├─ a.js
└─ icon.svg

Inject file references into index.html if the files with the extension .css or .js.

<!doctype html>
<html>
  <head><link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css">
    <link rel="stylesheet" href="files/a.css">
  </head>
  <body><script src="files/a.js"></script>
  </body>
</html>
config

Type: String|Object
Default: styleguide.json

The entire range of RSG API options is allowed. Usage example.

An object can be passed instead of a filename that contains the RSG API options.

pushstate

Type: String
Default: false

Enable HTML5 pushState. When this option is enabled, styleguide will use history API.

babelConfig

Type: Object
Default: null

A usage example is below. See the babel docs for the complete list.

{
  babelConfig: {
    stage: 0
  }
}
browserifyConfig

Type: Object
Default: { standalone: 'Contents', debug: true }

A usage example is below. See the browserify docs for the complete list.

{
  extensions: ['', '.js', '.jsx']
}

watch

Type: String Default: false

Enables watchify for when the input files change, speeding up rebuild time.

rsg.generate()

Generate the files and their dependencies into a styleguide output.

Demo

Get the demo running locally:

git clone git@github.com:pocotan001/react-styleguide-generator.git
cd react-styleguide-generator/example/
npm install
npm start

Visit http://localhost:3000/ in your browser.

Troubleshooting

Error: No suitable component definition found.

Make sure your component contains displayName and render().

You can’t perform that action at this time.