From d6ea9b0fc108f6ae6be3c3a0ab22a7842924f633 Mon Sep 17 00:00:00 2001 From: Nick Plekhanov Date: Thu, 7 Apr 2016 01:45:26 +0200 Subject: [PATCH] Fixed typos in docs and moved CONTRIBUTING guide to one level up for ease of access. --- CHANGELOG.md | 2 +- .github/CONTRIBUTING.md => CONTRIBUTING.md | 0 README.md | 14 ++++----- docs/api.md | 34 +++++++++++----------- docs/guidelines.md | 8 ++--- docs/known_issues.md | 8 ++--- docs/setting-up-for-css.md | 25 ++++++++-------- 7 files changed, 45 insertions(+), 46 deletions(-) rename .github/CONTRIBUTING.md => CONTRIBUTING.md (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8279c8c27698..a6ea302ececb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ ### v1.3.0 * Load the `.babelrc` manually. Fixed: [#41](https://github.com/kadirahq/react-storybook/issues/41) -* Add a better contributing guide. See [CONTRIBUTING.md)](https://github.com/kadirahq/react-storybook/blob/master/.github/CONTRIBUTING.md) +* Add a better contributing guide. See [CONTRIBUTING.md](https://github.com/kadirahq/react-storybook/blob/master/CONTRIBUTING.md) * Add a development utility `npm run dev` which watches "src" directory and run `npm run prepublish`. ### v1.2.0 diff --git a/.github/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 100% rename from .github/CONTRIBUTING.md rename to CONTRIBUTING.md diff --git a/README.md b/README.md index c51e8ef61c27..291ed1ab6ea8 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ This functionality allows you to develop UI components rapidly without worrying Let's look at what React Storybook does. First clone the following repo: -``` +```sh git clone https://github.com/kadira-samples/react-storybook-demo ``` @@ -33,7 +33,7 @@ git clone https://github.com/kadira-samples/react-storybook-demo Then apply the following commands: -``` +```sh npm install npm run storybook ``` @@ -48,7 +48,7 @@ Edit some of the components in the `components` directory and see how they refle Now let's add support for React Storybook to your app. First of all, add the `@kadira/storybook` NPM package to your app: -``` +```sh npm i --save-dev @kadira/storybook ``` @@ -97,20 +97,20 @@ Here, we simply have two stories for the built-in `button` component. But, you c ### Configurations -Now you need to tell Storybook where it should load the stories from. For that, you need to write a simple configuration file. Add the following file to `.storybook/config.js`: +Now you need to tell Storybook where it should load the stories from. For that, you need to write a simple configuration file. Add the following content to `.storybook/config.js`: ```js import { configure } from '@kadira/storybook'; function loadStories() { require('../components/stories/button'); - // require as many as stories you need. + // require as many stories as you need. } configure(loadStories, module); ``` -That's it. Now simply run “npm run storybook” and start developing your components. +That's it. Now simply run `npm run storybook` and start developing your components. > Check this app to see it in action: https://github.com/kadira-samples/react-storybook-simple-demo @@ -123,7 +123,7 @@ There are many things you can do with React Storybook. You can explore them with * [API and configurations](docs/api.md) * [Guideline for writing stories](docs/guidelines.md) * [Known Issues](docs/known_issues.md) -* [How to Contribute](.github/CONTRIBUTING.md) +* [How to Contribute](CONTRIBUTING.md) * How React Storybook works (coming soon) ## Sample Apps diff --git a/docs/api.md b/docs/api.md index 52d614f09781..51b78366a707 100644 --- a/docs/api.md +++ b/docs/api.md @@ -15,7 +15,7 @@ You can configure React Storybook in different ways. We'll discuss them here. * [Loading Modules](#loading-modules) * [Load Common CSS Files](#load-common-css-files) * [Configure Modules for Testing](#configure-modules-for-testing) -* [Custom webpack Configurations](#custom-webpack-configurations) +* [Custom Webpack Configurations](#custom-webpack-configurations) ## Command Line API @@ -23,9 +23,9 @@ React Storybook comes with a command line API, which you usually use inside a NP ### Port -You must set a port where the React Storybook starts it's web server. Here's how to specify it: +You must set a port on which React Storybook starts its web server. Here's how to specify it: -``` +```sh start-storybook -p 6977 ``` @@ -35,7 +35,7 @@ Sometimes, you ship your static files directly inside your project. In Meteor ap Here's how to tell React Storybook to use that directory to load static files: -``` +```sh start-storybook -p 6977 -s ./public ``` @@ -45,7 +45,7 @@ React Storybook uses `.storybook` directory as a default location for its [basic Here's how to tell React Storybook to use a custom directory to load your configuration files: -``` +```sh start-storybook -p 6977 -s ./public -c ./storybook-config ``` @@ -70,11 +70,11 @@ storiesOf('Button', module) )); ``` -Here you can chain the `add` method and create as many as stories as you need. +Here you can chain the `add` method and create as many stories as you need. ### Creating Actions -Usually, our components accept event handlers. Actions help us to debug those event handlers. These actions are logged in the `Action Logger` in React Storybook. +Usually, our components accept event handlers. Actions help us to debug those event handlers. These actions are logged in the `Action Logger` info window in React Storybook. This is how we can create an action: @@ -88,7 +88,7 @@ storiesOf('Button', module) )); ``` -Here we create an action named `clicked`. It gives a function to the onClick prop in our button. +Here we create an action named `click the button`. It gives a function to the `onClick` prop in our button. Then, when you click on the button, it will log something like this into the Action Logger: @@ -105,13 +105,13 @@ Then, when you click on the button, it will log something like this into the Act } ``` -Here we can see the name we've mentioned when creating the action. After that, we can see the arguments passed to the event handler onClick. In this case, we've three arguments. `[SyntheticMouseEvent]` is the actual event object passed by React and you can use that to get more details. +Here we can see the name we've mentioned when creating the action. After that, we can see the arguments passed to the `onClick` event handler. In this case, we've three arguments. `[SyntheticMouseEvent]` is the actual event object passed by React and you can use that to get more details. > For simplicity, React Storybook does not show the actual object. Instead it will show `[SyntheticMouseEvent]`. ## Basic Configurations -React Storybook uses a JavaScript file at `.storybook/config.js` as the entry point. This is the file loaded by webpack when it's initializing. You can configure a few things inside it. +React Storybook uses a JavaScript file located at `.storybook/config.js` as the entry point. This is the file loaded by webpack when it's initializing. You can configure a few things inside it. ### Loading Modules @@ -122,7 +122,7 @@ import { configure } from '@kadira/storybook'; function loadStories() { require('../components/stories/button'); - // require as many as stories you need. + // require as many stories as you need. } configure(loadStories, module); @@ -144,7 +144,7 @@ configure(loadStories, module); ### Load Common CSS Files -Sometimes your app has some common CSS files, so this is the best place to load them. In our Redux to-do example, we load todomvc CSS like this: +Sometimes your app has some common CSS files, so this is the best place to load them. In our [Redux to-do example](https://github.com/kadira-samples/react-storybook-demo), we load todomvc CSS like this: ```js import { configure } from '@kadira/storybook'; @@ -163,7 +163,7 @@ React Storybook is not your app. So, sometimes you won’t be able to use some o Let's have a look at an example. -In some of our apps, we use [`react-komposer`](https://github.com/kadirahq/react-komposer) (especially in Mantra apps). So, if you use any container created by `react-komposer`, it usually throws an error since React Storybook does not initialize them properly. +In some of our apps we use [`react-komposer`](https://github.com/kadirahq/react-komposer) (especially in Mantra apps). So, if you use any container created by `react-komposer`, it usually throws an error since React Storybook does not initialize them properly. In such a scenario, you can disable `react-komposer` like this: @@ -180,7 +180,7 @@ function loadStories() { configure(loadStories, module); ``` -## Custom webpack Configurations +## Custom Webpack Configurations React Storybook is built on top of webpack. If you need, you can customize the webpack configurations used by React Storybook. @@ -209,6 +209,6 @@ module.exports = { > You can pass options to this config file as you wish. But, there are some stuff like devServer we'll always add by default.
> So, usually you need to use this config for doing following things: -> * For loading CSS. -> * For adding custom resolve extensions. -> * For adding resolve aliases. +> * for loading CSS, +> * for adding custom resolve extensions, +> * for adding resolve aliases. diff --git a/docs/guidelines.md b/docs/guidelines.md index d4b7a851ec3a..bc8d0449c824 100644 --- a/docs/guidelines.md +++ b/docs/guidelines.md @@ -1,11 +1,11 @@ # Guidelines for Creating Stories -* Write UI components by passing data via props. In this way, you can isolate UI components easily. (Maybe you can follow a pattern like Mantra.) +* Write UI components by passing data via props. In this way, you can isolate UI components easily. (Maybe you can follow a pattern like [Mantra](https://voice.kadira.io/sneak-peek-mantra-7161624acaa7).) * Do not write app-specific code inside your UI components. -* Write your stories close to your UI components. A directory called 'stories' inside your components directory is a good idea. -* In Meteor, you may need to use a directory name with '.stories' or create it inside the 'tests' directory. Otherwise, these story files will be loaded by Meteor. +* Write your stories close to your UI components. A directory called `stories` inside your components directory is a good idea. +* In Meteor, you may need to use a directory name with `.stories` or create it inside the `tests` directory. Otherwise, these story files will be loaded by Meteor. * In a single story module, create stories for a single component. -* Prefix story names with a dot (.). For example, see: +* Prefix story names with a dot (`.`). For example: ```js storiesOf('core.Button', module) diff --git a/docs/known_issues.md b/docs/known_issues.md index cfc3f6a646c8..3aba919d10ef 100644 --- a/docs/known_issues.md +++ b/docs/known_issues.md @@ -2,9 +2,9 @@ ## NPM 404 Error -This package is published as a NPM [scoped package](https://docs.npmjs.com/misc/scope). So, if you get a 404 error while doing `npm install`, that seems like you are using a different NPM registry(or a NPM proxy). +This package is published as a NPM [scoped package](https://docs.npmjs.com/misc/scope). So, if you get a 404 error while doing `npm install`, that seems like you are using a different NPM registry (or a NPM proxy). -**Try to use the default registy.** +**Try to use the default registry.** See more: https://github.com/kadirahq/react-storybook/issues/15 @@ -20,7 +20,7 @@ npm i ## Issues with Babel 5 -If you are using babel 5 inside your project, you will get some errors on parsing modules. -Try to migrate your project to babel 6. +If you are using Babel 5 inside your project, you will get some errors on parsing modules. +Try to [migrate your project](https://babeljs.io/blog/2015/10/31/setting-up-babel-6) to Babel 6. See more: https://github.com/kadirahq/react-storybook/issues/16 diff --git a/docs/setting-up-for-css.md b/docs/setting-up-for-css.md index e108884a6e56..a40b8e9c1235 100644 --- a/docs/setting-up-for-css.md +++ b/docs/setting-up-for-css.md @@ -1,15 +1,15 @@ -# Setting up for CSS +# Setting Up for CSS CSS is a dark area of React. There are tons of ways to write CSS with React. -> Arunoda wrote as [article](https://voice.kadira.io/state-of-react-and-css-501d179443d3) about that recently as well. Have a [look at it](https://voice.kadira.io/state-of-react-and-css-501d179443d3). +> Arunoda wrote an [article](https://voice.kadira.io/state-of-react-and-css-501d179443d3) about that recently as well. Have a [look at it](https://voice.kadira.io/state-of-react-and-css-501d179443d3). So, React Storybook allows you to write CSS as you like. It's configurable. ## TOC * [CSS in JavaScript](#css-in-javascript) -* [CSS webpack Loaders](#css-webpack-loaders) +* [CSS Webpack Loaders](#css-webpack-loaders) * [CSS with Meteor](#css-with-meteor) ## CSS in JavaScript @@ -18,11 +18,11 @@ By default, React Storybook doesn't come with any CSS setup. That's because ther This is also true if you use a UI framework like [Material UI](https://github.com/callemall/material-ui). -## CSS webpack Loaders +## CSS Webpack Loaders -Usually, we use CSS with the help of webpack and we use CSS loaders inside our app. You can ask React Storybook to use the same loaders. It's pretty simple. +Usually, we use CSS with the help of Webpack and we use CSS loaders inside our app. You can ask React Storybook to use the same loaders. It's pretty simple. -Let's say you are using the style loader inside your app. Then, your webpack config would usually look like this: +Let's say you are using the style loader inside your app. Then, your Webpack config would usually look like this: ```js var path = require('path') @@ -54,10 +54,9 @@ Now, let's customize React Stoybook to use these CSS modules. > By default, React Storybook uses the babel loader for JavaScript. So, you don't need to add it. -Create a file `.storybook/webpack.config.js`. Then add the following content to it: +Create a file `.storybook/webpack.config.js` with the following content: ```js - const path = require('path'); module.exports = { @@ -74,18 +73,18 @@ module.exports = { ``` -It's exactly similar to what we had before, but we have simply chosen to include the parent directory. That's because we are inside the “.storybook” directory. +It's exactly similar to what we had before, but we have simply chosen to include the parent directory. That's because we are inside the `.storybook` directory. **That's it.** -Now you can work with CSS files. Follow these steps: +Now you can work with CSS files. Just follow these simple steps: * If your app has a root CSS file(s), simply import it into `.storybook/config.js`. * If you've imported CSS files directly into a component, you don't have to do anything. * Just like this, you can use any CSS loader you want, whether it's CSS Modules, SCSS, Less or anything. -> [Refer to this project for more information.](https://github.com/kadira-samples/react-storybook-demo) +> [Refer to this project for more information](https://github.com/kadira-samples/react-storybook-demo). ## CSS with Meteor @@ -94,14 +93,14 @@ Meteor will automatically import any CSS files into your app. You can also use L React Storybook cannot import CSS automatically. But instead, you can do this: * You can configure React Storybook to use a CSS loader. -* Then import the main CSS file(s) into `.storybook/config.js`. +* Then import the main CSS file(s) into `.storybook/config.js` file. * Then import component-specific CSS file(s) right into your story files. **Let's configure React Storybook to use the style loader inside a Meteor app.** * Make sure you've added React Storybook properly inside the app. * Then install style loader with `npm install --save-dev style-loader raw-loader`. -* Then create a file called `.storybook/webpack.config.js` with the following content +* Then create a file called `.storybook/webpack.config.js` with the following content: ```js const path = require('path');