fix #152 improve documentation

.bookignore

@@ -0,0 +1,4 @@
+src/
+build/
+package.json
+webpack*

.gitignore

@@ -5,3 +5,6 @@ es
 lib
 dist
 .idea
+
+# docs generated files
+_book

.npmignore

@@ -0,0 +1,5 @@
+# doc folders
+docs
+_book
+.bookignore
+book.json

CNAME

@@ -0,0 +1 @@
+redux-actions.js.org

README.md

@@ -6,258 +6,38 @@
 
 [Flux Standard Action](https://github.com/acdlite/flux-standard-action) utilities for Redux.
 
-## Installation
-
-```bash
-npm install --save redux-actions
-```
-
-The [npm](https://www.npmjs.com) package provides a [CommonJS](http://webpack.github.io/docs/commonjs.html) build for use in Node.js, and with bundlers like [Webpack](http://webpack.github.io/) and [Browserify](http://browserify.org/). It also includes an [ES modules](http://jsmodules.io/) build that works well with [Rollup](http://rollupjs.org/) and [Webpack2](https://webpack.js.org)'s tree-shaking.
-
-If you don’t use [npm](https://www.npmjs.com), you may grab the latest [UMD](https://unpkg.com/redux-actions@latest/dist) build from [unpkg](https://unpkg.com) (either a [development](https://unpkg.com/redux-actions@latest/dist/redux-actions.js) or a [production](https://unpkg.com/redux-actions@latest/dist/redux-actions.min.js) build). The UMD build exports a global called `window.ReduxActions` if you add it to your page via a `<script>` tag. We *don’t* recommend UMD builds for any serious application, as most of the libraries complementary to Redux are only available on [npm](https://www.npmjs.com/search?q=redux).
-
-## Usage
-
-### `createAction(type, payloadCreator = Identity, ?metaCreator)`
-
-```js
-import { createAction } from 'redux-actions';
-```
-
-Wraps an action creator so that its return value is the payload of a Flux Standard Action.
-
-`payloadCreator` must be a function, `undefined`, or `null`. If `payloadCreator` is `undefined` or `null`, the identity function is used.
-
-Example:
-
-```js
-let noop = createAction('NOOP', amount => amount);
-// same as
-noop = createAction('NOOP');
-
-expect(noop(42)).to.deep.equal({
-  type: 'NOOP',
-  payload: 42
-});
-```
-
-If the payload is an instance of an [Error
-object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error),
-redux-actions will automatically set ```action.error``` to true.
-
-Example:
-
-```js
-const noop = createAction('NOOP');
-
-const error = new TypeError('not a number');
-expect(noop(error)).to.deep.equal({
-  type: 'NOOP',
-  payload: error,
-  error: true
-});
-```
-
-`createAction` also returns its `type` when used as type in `handleAction` or `handleActions`.
-
-Example:
-
-```js
-const noop = createAction('INCREMENT');
-
-// As parameter in handleAction:
-handleAction(noop, {
-  next(state, action) {...},
-  throw(state, action) {...}
-});
-
-// As object key in handleActions:
-const reducer = handleActions({
-  [noop]: (state, action) => ({
-    counter: state.counter + action.payload
-  })
-}, { counter: 0 });
-```
-
-**NOTE:** The more correct name for this function is probably `createActionCreator()`, but that seems a bit redundant.
-
-Use the identity form to create one-off actions:
-
-```js
-createAction('ADD_TODO')('Use Redux');
-```
-
-`metaCreator` is an optional function that creates metadata for the payload. It receives the same arguments as the payload creator, but its result becomes the meta field of the resulting action. If `metaCreator` is undefined or not a function, the meta field is omitted.
-
-### `createActions(?actionMap, ?...identityActions)`
-
-```js
-import { createActions } from 'redux-actions';
-```
-
-Returns an object mapping action types to action creators. The keys of this object are camel-cased from the keys in `actionMap` and the string literals of `identityActions`; the values are the action creators.
-
-`actionMap` is an optional object and a recursive data structure, with action types as keys, and whose values **must** be either
-
-- a function, which is the payload creator for that action
-- an array with `payload` and `meta` functions in that order, as in [`createAction`](#createactiontype-payloadcreator--identity-metacreator)
-    - `meta` is **required** in this case (otherwise use the function form above)
-- an `actionMap`
-
-`identityActions` is an optional list of positional string arguments that are action type strings; these action types will use the identity payload creator.
-
-
-```js
-const { actionOne, actionTwo, actionThree } = createActions({
-  // function form; payload creator defined inline
-  ACTION_ONE: (key, value) => ({ [key]: value }),
-
-  // array form
-  ACTION_TWO: [
-    (first) => [first],             // payload
-    (first, second) => ({ second }) // meta
-  ],
-
-  // trailing action type string form; payload creator is the identity
-}, 'ACTION_THREE');
+### Table of Contents
+* [Getting Started](#gettingstarted)
+  * [Installation](#installation)
+  * [Usage](#usage)
+* [Documentation](#documentation)
 
-expect(actionOne('key', 1)).to.deep.equal({
-  type: 'ACTION_ONE',
-  payload: { key: 1 }
-});
-
-expect(actionTwo('first', 'second')).to.deep.equal({
-  type: 'ACTION_TWO',
-  payload: ['first'],
-  meta: { second: 'second' }
-});
-
-expect(actionThree(3)).to.deep.equal({
-  type: 'ACTION_THREE',
-  payload: 3,
-});
-```
-
-If `actionMap` has a recursive structure, its leaves are used as payload and meta creators, and the action type for each leaf is the combined path to that leaf:
-
-```js
-const actionCreators = createActions({
-  APP: {
-    COUNTER: {
-      INCREMENT: [
-        amount => ({ amount }),
-        amount => ({ key: 'value', amount })
-      ],
-      DECREMENT: amount => ({ amount: -amount }),
-      SET: undefined // given undefined, the identity function will be used
-    },
-    NOTIFY: [
-      (username, message) => ({ message: `${username}: ${message}` }),
-      (username, message) => ({ username, message })
-    ]
-  }
-});
-
-expect(actionCreators.app.counter.increment(1)).to.deep.equal({
-  type: 'APP/COUNTER/INCREMENT',
-  payload: { amount: 1 },
-  meta: { key: 'value', amount: 1 }
-});
-expect(actionCreators.app.counter.decrement(1)).to.deep.equal({
-  type: 'APP/COUNTER/DECREMENT',
-  payload: { amount: -1 }
-});
-expect(actionCreators.app.counter.set(100)).to.deep.equal({
-  type: 'APP/COUNTER/SET',
-  payload: 100
-});
-expect(actionCreators.app.notify('yangmillstheory', 'Hello World')).to.deep.equal({
-  type: 'APP/NOTIFY',
-  payload: { message: 'yangmillstheory: Hello World' },
-  meta: { username: 'yangmillstheory', message: 'Hello World' }
-});
-```
-When using this form, you can pass an object with key `namespace` as the last positional argument (the default is `/`).
-
-### `handleAction(type, reducer | reducerMap = Identity, defaultState)`
-
-```js
-import { handleAction } from 'redux-actions';
-```
 
-Wraps a reducer so that it only handles Flux Standard Actions of a certain type.
+# Getting Started {#gettingstarted}
 
-If a `reducer` function is passed, it is used to handle both normal actions and failed actions. (A failed action is analogous to a rejected promise.) You can use this form if you know a certain type of action will never fail, like the increment example above.
-
-Otherwise, you can specify separate reducers for `next()` and `throw()` using the `reducerMap` form. This API is inspired by the ES6 generator interface.
+## Installation
 
-```js
-handleAction('FETCH_DATA', {
-  next(state, action) {...},
-  throw(state, action) {...}
-}, defaultState);
+```bash
+$ npm install --save redux-actions
 ```
 
-If either `next()` or `throw()` are `undefined` or `null`, then the identity function is used for that reducer.
-
-If the reducer argument (`reducer | reducerMap`) is `undefined`, then the identity function is used.
-
-The third parameter `defaultState` is required, and is used when `undefined` is passed to the reducer.
+or
 
-### `handleActions(reducerMap, defaultState, )`
-
-```js
-import { handleActions } from 'redux-actions';
 ```
-
-Creates multiple reducers using `handleAction()` and combines them into a single reducer that handles multiple actions. Accepts a map where the keys are passed as the first parameter to `handleAction()` (the action type), and the values are passed as the second parameter (either a reducer or reducer map). The map must not be empty.
-
-If `reducerMap` has a recursive structure, its leaves are used as reducers, and the action type for each leaf is the path to that leaf. If a node's only children are `next()` and `throw()`, the node will be treated as a reducer. If the leaf is `undefined` or `null`, the identity function is used as the reducer. Otherwise, the leaf should be the reducer function. When using this form, you can pass an object with key `namespace` as the last positional argument (the default is `/`).
-
-The second parameter `defaultState` is required, and is used when `undefined` is passed to the reducer.
-
-(Internally, `handleActions()` works by applying multiple reducers in sequence using [reduce-reducers](https://github.com/acdlite/reduce-reducers).)
-
-Example:
-
-```js
-const reducer = handleActions({
-  INCREMENT: (state, action) => ({
-    counter: state.counter + action.payload
-  }),
-
-  DECREMENT: (state, action) => ({
-    counter: state.counter - action.payload
-  })
-}, { counter: 0 });
+$ yarn add redux-actions
 ```
 
-### `combineActions(...types)`
+The [npm](https://www.npmjs.com) package provides a [CommonJS](http://webpack.github.io/docs/commonjs.html) build for use in Node.js, and with bundlers like [Webpack](http://webpack.github.io/) and [Browserify](http://browserify.org/). It also includes an [ES modules](http://jsmodules.io/) build that works well with [Rollup](http://rollupjs.org/) and [Webpack2](https://webpack.js.org)'s tree-shaking.
 
-Combine any number of action types or action creators. `types` is a list of positional arguments which can be action type strings, symbols, or action creators.
+The [UMD](https://unpkg.com/redux-actions@latest/dist) build exports a global called `window.ReduxActions` if you add it to your page via a `<script>` tag. We *don’t* recommend UMD builds for any serious application, as most of the libraries complementary to Redux are only available on [npm](https://www.npmjs.com/search?q=redux).
 
-This allows you to reduce multiple distinct actions with the same reducer.
+## Usage
 
 ```js
-const { increment, decrement } = createActions({
-  INCREMENT: amount => ({ amount }),
-  DECREMENT: amount => ({ amount: -amount }),
-})
-
-const reducer = handleAction(combineActions(increment, decrement), {
-  next: (state, { payload: { amount } }) => ({ ...state, counter: state.counter + amount }),
-  throw: state => ({ ...state, counter: 0 }),
-}, { counter: 10 })
-
-expect(reducer(undefined, increment(1)).to.deep.equal({ counter: 11 })
-expect(reducer(undefined, decrement(1)).to.deep.equal({ counter: 9 })
-expect(reducer(undefined, increment(new Error)).to.deep.equal({ counter: 0 })
-expect(reducer(undefined, decrement(new Error)).to.deep.equal({ counter: 0 })
-```
+import { createActions, handleActions, combineActions } from 'redux-actions'
 
-Here's an example using `handleActions`:
+const defaultState = { counter: 10 };
 
-```js
 const { increment, decrement } = createActions({
   INCREMENT: amount => ({ amount }),
   DECREMENT: amount => ({ amount: -amount })
@@ -267,43 +47,18 @@ const reducer = handleActions({
   [combineActions(increment, decrement)](state, { payload: { amount } }) {
     return { ...state, counter: state.counter + amount };
   }
-}, { counter: 10 });
-
-expect(reducer({ counter: 5 }, increment(5))).to.deep.equal({ counter: 10 });
-expect(reducer({ counter: 5 }, decrement(5))).to.deep.equal({ counter: 0 });
-expect(reducer({ counter: 5 }, { type: 'NOT_TYPE', payload: 1000 })).to.equal({ counter: 5 });
-expect(reducer(undefined, increment(5))).to.deep.equal({ counter: 15 });
-```
-
-## Usage with middleware
-
-redux-actions is handy all by itself, however, its real power comes when you combine it with middleware.
-
-The identity form of `createAction` is a great way to create a single action creator that handles multiple payload types. For example, using [redux-promise](https://github.com/acdlite/redux-promise) and [redux-rx](https://github.com/acdlite/redux-rx):
-
-```js
-const addTodo = createAction('ADD_TODO');
-
-// A single reducer...
-handleAction('ADD_TODO', (state = { todos: [] }, action) => ({
-  ...state,
-  todos: [...state.todos, action.payload]
-}));
+}, defaultState);
 
-// ...that works with all of these forms:
-// (Don't forget to use `bindActionCreators()` or equivalent.
-// I've left that bit out)
-addTodo('Use Redux')
-addTodo(Promise.resolve('Weep with joy'));
-addTodo(Observable.of(
-  'Learn about middleware',
-  'Learn about higher-order stores'
-)).subscribe();
+export default reducer;
 ```
 
-## See also
+For more complex scenarios we recommend reading our [documentation](https://redux-actions.js.org/).
 
-Use redux-actions in combination with FSA-compliant libraries.
+# Documentation
 
-- [redux-promise](https://github.com/acdlite/redux-promise) - Promise middleware
-- [redux-rx](https://github.com/acdlite/redux-rx) - Includes observable middleware.
+* [Introduction](/docs/introduction)
+* [API](/docs/api)
+* [Middleware](/docs/middleware)
+* [External Resources](/docs/ExternalResources.md)
+* [Change Log](/docs/ChangeLog.md)
+* [Contributors](/docs/Contributors.md)

SUMMARY.md

@@ -0,0 +1,14 @@
+# Summary
+
+* [Read Me](/README.md)
+* [1. Introduction](/docs/introduction/README.md)
+  * [1.1 Motivation](docs/introduction/Motivation.md)
+  * [1.2 Tutorial](/docs/introduction/Tutorial.md)
+* [2. API Reference](/docs/api/README.md)
+  * [2.1 createAction(s)](/docs/api/createAction.md)
+  * [2.2 handleAction(s)](/docs/api/handleAction.md)
+  * [2.3 combineActions](/docs/api/combineActions.md)
+* [3. Middleware](/docs/middleware/README.md)
+* [4. External Resources](/docs/ExternalResources.md)
+* [5. Change Log](/docs/ChangeLog.md)
+* [6. Contributors](/docs/Contributors.md)

book.json

@@ -0,0 +1,22 @@
+{
+  "gitbook": ">= 3.0.0",
+  "title": "Redux Actions",
+  "plugins": ["edit-link", "prism", "-highlight", "github", "anchorjs"],
+  "pluginsConfig": {
+    "edit-link": {
+      "base": "https://github.com/acdlite/redux-actions/tree/master",
+      "label": "Edit This Page"
+    },
+    "github": {
+      "url": "https://github.com/acdlite/redux-actions/"
+    },
+    "sharing": {
+      "facebook": true,
+      "twitter": true,
+      "google": false,
+      "weibo": false,
+      "instapaper": false,
+      "vk": false
+    }
+  }
+}

docs/ChangeLog.md

@@ -0,0 +1,4 @@
+# Change Log
+
+This project adheres to [Semantic Versioning](http://semver.org/).
+Every release, along with the migration instructions, is documented on the Github [Releases](https://github.com/acdlite/redux-actions/releases) page.