Added initial docs site with proposed table of contents and some content pages

Author: mpeyper

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 coverage
 lib
+.docz

.prettierignore

@@ -0,0 +1 @@
+site

README.md

@@ -1,16 +1,23 @@
+---
+name: Getting Started
+route: '/'
+---
+
 <div align="center">
-<h1>react-hooks-testing-library</h1>
+  <h1>react-hooks-testing-library</h1>
 
-<a href="https://www.emojione.com/emoji/1f40f">
-  <img
-    height="80"
-    width="80"
-    alt="ram"
-    src="https://raw.githubusercontent.com/mpeyper/react-hooks-testing-library/master/other/ram.png"
-  />
-</a>
+  <a href="https://www.emojione.com/emoji/1f40f">
+    <img
+      height="80"
+      width="80"
+      alt="ram"
+      src="https://raw.githubusercontent.com/mpeyper/react-hooks-testing-library/master/other/ram.png"
+    />
+  </a>
 
-<p>Simple component wrapper and utilities for testing React hooks.</p>
+  <p>
+    Simple component wrapper and utilities for testing React hooks.
+  </p>
 
 </div>
 
@@ -106,33 +113,7 @@ npm install --save-dev react-hooks-testing-library
 
 ## API
 
-### `renderHook(callback[, options])`
-
-Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders.
-
-> _Note: `testHook` has been renamed to `renderHook`. `testHook` will continue work in the current version with a deprecation warning, but will be removed in a future version._
->
-> **_You should update any usages of `testHook` to use `renderHook` instead._**
-
-#### Arguments
-
-- `callback` (`function()`) - function to call each render. This function should call one or more hooks for testing.
-- `options` (`object`) - accept the following settings:
-  - `initialProps` (`object`) - the initial values to pass to the `callback` function
-  - `wrapper` (`component`) - pass a React Component as the wrapper option to have it rendered around the inner element. This is most useful for creating reusable custom render functions for common data providers
-
-#### Returns
-
-- `result` (`object`)
-  - `current` (`any`) - the return value of the `callback` function
-  - `error` (`Error`) - the error that was thrown if the `callback` function threw an error during rendering
-- `waitForNextUpdate` (`function`) - returns a `Promise` that resolves the next time the hook renders, commonly when state is updated as the result of a asynchronous action.
-- `rerender` (`function([newProps])`) - function to rerender the test component including any hooks called in the `callback` function. If `newProps` are passed, the will replace the `initialProps` passed the the `callback` function for future renders.
-- `unmount` (`function()`) - function to unmount the test component, commonly used to trigger cleanup effects for `useEffect` hooks.
-
-### `act(callback)`
-
-This is the same [`act` function](https://reactjs.org/docs/hooks-faq.html#how-to-test-components-that-use-hooks) that is exported by `react-test-renderer`.
+See the [API documentation](/docs/reference/api.mdx)
 
 ## Contributors
 

docs/reference/api.md

@@ -0,0 +1,38 @@
+---
+name: API
+menu: Reference
+route: '/reference/api'
+---
+
+# API
+
+## `renderHook(callback[, options])`
+
+Renders a test component that will call the provided `callback`, including any hooks it calls, every time it renders.
+
+> _Note: `testHook` has been renamed to `renderHook`. `testHook` will continue work in the current version with a deprecation warning, but will be removed in a future version._
+>
+> **_You should update any usages of `testHook` to use `renderHook` instead._**
+
+### Arguments
+
+- `callback` (`function([props])`) - function to call each render. This function should call one or more hooks for testing
+  - The `props` passed into the callback will be the `initialProps` provided in the `options` until new props are provided by a `rerender` call
+- `options` (`object`)
+  - `initialProps` (`object`) - the initial values to pass to the `callback` function
+  - `wrapper` (`component`) - pass a React component to wrap the test component
+    - This is usually used to add context providers from `React.createContext` for the hook access with `useContext`
+
+### Returns
+
+- `result` (`object`)
+  - `current` (`any`) - the return value of the `callback` function
+  - `error` (`Error`) - the error that was thrown if the `callback` function threw an error during rendering
+- `waitForNextUpdate` (`function`) - returns a `Promise` that resolves the next time the hook renders, commonly when state is updated as the result of a asynchronous action
+- `rerender` (`function([newProps])`) - function to rerender the test component including any hooks called in the `callback` function
+  - If `newProps` are passed, the will replace the `initialProps` passed the the `callback` function for future renders
+- `unmount` (`function()`) - function to unmount the test component, commonly used to trigger cleanup effects for `useEffect` hooks
+
+## `act(callback)`
+
+This is the same [`act` function](https://testing-library.com/docs/react-testing-library/api#act) that is exported by `react-testing-library`.

docs/usage/advanced-hooks.md

@@ -0,0 +1,152 @@
+---
+name: Advanced Hooks
+menu: Usage
+route: '/usage/advanced-hooks'
+---
+
+# Advanced Hooks
+
+## Providing Props
+
+Sometimes a hook relies on the props passed to it in order to do it's thing. For example the `useCounter` hook we built in the [Basic Hooks](/usage/basic-hooks) section could easily accept the initial value of the counter:
+
+```js
+import { useState, useCallback } from 'react'
+
+export default function useCounter(initialValue = 0) {
+  const [count, setCount] = useState(initialValue)
+  const increment = useCallback(() => setCount(count + 1), [count])
+  return { count, increment }
+}
+```
+
+Overriding the `initialValue` prop in out test is as easy as calling the hook with the value we want to use:
+
+```js
+import { renderHook, act } from 'react-hooks-testing-library'
+import useCounter from './useCounter'
+
+test('should increment counter from custom initial value', () => {
+  const { result } = renderHook(() => useCounter(9000))
+
+  act(() => {
+    result.current.increment()
+  })
+
+  expect(result.current.count).toBe(9001)
+})
+```
+
+### Changing Props
+
+Many of the hook primitives use an array of dependent values to determine when to perform specific actions, such as recalculating an expensive value or running an effect. If we update our `useCounter` hook to have a `reset` function that resets the value to the `initialValue` it might look something like this:
+
+```js
+import { useState, useCallback } from 'react'
+
+export default function useCounter(initialValue = 0) {
+  const [count, setCount] = useState(initialValue)
+  const increment = useCallback(() => setCount(count + 1), [count])
+  const reset = useCallback(() => setCount(initialValue), [initialValue])
+  return { count, increment, reset }
+}
+```
+
+Now, the only time the `reset` function will be updated is if `initialValue` changes. The most basic way to handle changing the input props of our hook in a test is to simply update the value in a variable and rerender the hook:
+
+```js
+import { renderHook, act } from 'react-hooks-testing-library'
+import useCounter from './useCounter'
+
+test('should reset counter to updated initial value', () => {
+  let initialValue = 0
+  const { result, rerender } = renderHook(() => useCounter(initialValue))
+
+  initialValue = 10
+  rerender()
+
+  act(() => {
+    result.current.reset()
+  })
+
+  expect(result.current.count).toBe(10)
+})
+```
+
+This is fine, but if there are lots of props, it can become a bit difficult to have variables to keep track of them all. Another option is to use the `initialProps` option and `newProps` of `rerender`:
+
+```js
+import { renderHook, act } from 'react-hooks-testing-library'
+import useCounter from './useCounter'
+
+test('should reset counter to updated initial value', () => {
+  const { result, rerender } = renderHook(({ initialValue }) => useCounter(initialValue), {
+    initialProps: { initialValue: 0 }
+  })
+
+  rerender({ initialValue: 10 })
+
+  act(() => {
+    result.current.reset()
+  })
+
+  expect(result.current.count).toBe(10)
+})
+```
+
+Another case where this is useful is when you want limit the scope of the variables being closed over to just be inside the hook callback. The following (contrived) example fails because the `id` value changes for both the setup and cleanup of the `useEffect` call:
+
+```js
+import { useEffect } from 'react'
+import { renderHook } from "react-hooks-testing-library"
+import sideEffect from './sideEffect
+
+test("should clean up side effect", () => {
+  let id = "first"
+  const { rerender } = renderHook(() => {
+    useEffect(() => {
+      sideEffect.start(id)
+      return () => {
+        sideEffect.stop(id) // this id will get the new value when the effect is cleaned up
+      }
+    }, [id])
+  })
+
+  id = "second"
+  rerender()
+
+  expect(sideEffect.get("first")).toBe(false)
+  expect(sideEffect.get("second")).toBe(true)
+})
+```
+
+By using the `initialProps` and `newProps` the captured `id` value from the first render is used to clean up the effect, allowing the test to pass as expected:
+
+```js
+import { useEffect } from 'react'
+import { renderHook } from "react-hooks-testing-library"
+import sideEffect from './sideEffect
+
+test("should clean up side effect", () => {
+  const { rerender } = renderHook(
+    ({ id }) => {
+      useEffect(() => {
+      sideEffect.start(id)
+      return () => {
+        sideEffect.stop(id) // this id will get the new value when the effect is cleaned up
+      }
+    }, [id])
+    },
+    {
+      initialProps: { id: "first" }
+    }
+  )
+
+  rerender({ id: "second" })
+
+  expect(thing.get("first")).toBe(false)
+  expect(thing.get("second")).toBe(true)
+})
+```
+
+This is a fairly obscure case, so pick the method that fits best for you and your test.

docs/usage/basic-hooks.md

@@ -0,0 +1,62 @@
+---
+name: Basic Hooks
+menu: Usage
+route: '/usage/basic-hooks'
+---
+
+# Basic Hooks
+
+## Rendering
+
+Imagine we have a simple hook that we want to test:
+
+```js
+import { useState, useCallback } from 'react'
+
+export default function useCounter() {
+  const [count, setCount] = useState(0)
+  const increment = useCallback(() => setCount(count + 1), [count])
+  return { count, increment }
+}
+```
+
+To test `useCounter` we need to render it using the `renderHook` function to provided by `react-hooks-testing-library`:
+
+```js
+import { renderHook } from 'react-hooks-testing-library'
+import useCounter from './useCounter'
+
+test('should use counter', () => {
+  const { result } = renderHook(() => useCounter())
+
+  expect(result.current.count).toBe(0)
+  expect(typeof result.current.increment).toBe('function')
+})
+```
+
+As you can see, the result's current value matches what is returned by our hook.
+
+## Updates
+
+The test shown above is great and all, but it doesn't actually test what we want to use the counter for, i.e. counting. We can easily improve this test by calling the `increment` function and checking that the `count` value increases:
+
+```js
+import { renderHook, act } from 'react-hooks-testing-library'
+import useCounter from './useCounter'
+
+test('should increment counter', () => {
+  const { result } = renderHook(() => useCounter())
+
+  act(() => {
+    result.current.increment()
+  })
+
+  expect(result.current.count).toBe(1)
+})
+```
+
+After `increment` is called, the current `count` value now reflects the new value returned by our hook.
+
+You may have also noticed that we also wrapped the `increment` call in `act`. This utility simulates how our hook will act in a browser, allowing us to update the values within it. For more details on `act`, please see the [React documentation](https://fb.me/react-wrap-tests-with-act).
+
+So there we have it, the first test for our `useCounter` hook.

doczrc.js

@@ -0,0 +1,23 @@
+export default {
+  files: '**/*.{md,mdx}',
+  dest: 'site',
+  public: './other',
+  ignore: ['CODE_OF_CONDUCT.md', 'CONTRIBUTING.md', 'LICENSE.md'],
+  htmlContext: {
+    favicon: '/public/ram.png'
+  },
+  themeConfig: {
+    mode: 'dark',
+    logo: {
+      src: '/public/ram.png',
+      margin: 'auto',
+      width: 128
+    }
+  },
+  menu: [
+    { name: 'Getting Started' },
+    { name: 'Usage', menu: ['Basic Hooks', 'Advanced Hooks', 'Async Hooks'] },
+    { name: 'Examples' },
+    { name: 'Reference', menu: ['FAQ', 'Troubleshooting', 'API'] }
+  ]
+}