[docs] Reorganize guides into new categories

reactive · Jun 8, 2019 · 5fc409d · 5fc409d
1 parent 4efd60c
commit 5fc409d
Show file tree

Hide file tree

Showing 8 changed files with 84 additions and 49 deletions.
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -2,21 +2,40 @@
 title: API Reference
 ---
 
+## Interface Definitions
 - [Resource](Resource.md)
-  - [RequestShape](RequestShape.md)
-- Hooks:
-  - [useResource](useResource.md)
-  - [useFetcher](useFetcher.md)
-  - [useCache](useCache.md)
-  - [useResultCache](useResultCache.md)
-  - [useSubscription](useSubscription.md)
-  - [useRetrieve](useRetrieve.md)
-  - [useInvalidator](useInvalidator.md)
-- Components:
-  - [RestProvider](RestProvider.md)
-  - [ExternalCacheProvider](ExternalCacheProvider.md)
-  - [NetworkErrorBoundary](NetworkErrorBoundary.md)
-- [Manager](Manager.md)s
-  - [NetworkManager](NetworkManager.md)
-  - [SubscriptionManager](SubscriptionManager.md)
-    - [PollingSubscription](PollingSubscription.md)
+- [RequestShape](RequestShape.md)
+
+## Hooks
+- [useResource](useResource.md)
+- [useFetcher](useFetcher.md)
+- [useCache](useCache.md)
+- [useResultCache](useResultCache.md)
+- [useSubscription](useSubscription.md)
+- [useRetrieve](useRetrieve.md)
+- [useInvalidator](useInvalidator.md)
+
+## Components
+- [RestProvider](RestProvider.md)
+- [ExternalCacheProvider](ExternalCacheProvider.md)
+- [NetworkErrorBoundary](NetworkErrorBoundary.md)
+
+## [Manager](Manager.md)s
+
+Extended the networking/state layer works through [managers](Manager.md).
+
+- [NetworkManager](NetworkManager.md)
+- [SubscriptionManager](SubscriptionManager.md)
+  - [PollingSubscription](PollingSubscription.md)
+
+## Testing
+
+Testing utilities are imported from `rest-hooks/testing`. These are useful
+helpers to ensure your code works as intended and are not meant to be shipped
+to production themselves.
+
+- [\<MockProvider />](MockProvider)
+- [makeRenderRestHook()](makeRenderRestHook)
+- [makeRestProvider()](makeRestProvider)
+- [makeExternalCacheProvider()](makeExternalCacheProvider)
+
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -67,3 +67,5 @@ const App = () => (
   </div>
 );
 ```
+
+[More about loading state](../guides/loading-state)
diff --git a/docs/getting-started/usage.md b/docs/getting-started/usage.md
@@ -74,6 +74,8 @@ Be sure to add all the properties you expect and mark them as readonly. [Mutatio
 
 Also be sure to provide the `pk()` function and `static urlRoot` string.
 
+APIs quickly get much more complicated! [Customizing Resources to fit your API](../guides/resource-types)
+
 ## [Use resource](../api/useResource.md)
 
 <!--DOCUSAURUS_CODE_TABS-->

diff --git a/docs/guides/loading-state.md b/docs/guides/loading-state.md
@@ -11,6 +11,8 @@ Normally you might do a check to see if the resource is loaded yet and manually
 specify each fallback condition in every component. However, since `rest-hooks`
 uses React's `Suspsense` API, it is much simpler to do here.
 
+## Using Suspense
+
 Simply place the `<Suspense />` component where you want to show a loading
 indicator. Often this will be just above your routes; but feel free to place
 it in multiple locations!
@@ -39,3 +41,11 @@ const App = () => (
 >
 > The `<Suspense/>` boundary must be placed in another component that is above the one
 > where `useResource()` and other hooks are used.
+
+
+## Without Suspense
+
+Suspense is the recommended way of handling loading state as it reduces complexity
+while integrating with [React.lazy()](https://reactjs.org/docs/code-splitting.html#reactlazy)
+and the soon-to-be-released concurrent mode. However, if you find yourself wanting to handle
+loading state manually you can adapt the [useStatefulResource()](./no-suspense.md) hook.
diff --git a/docs/guides/network-errors.md b/docs/guides/network-errors.md
@@ -1,6 +1,7 @@
 ---
 title: Dealing with network errors
 ---
+
 When you use the `useResource()` hook, React will suspend rendering while the network
 request takes place. But what happens if there is a network failure? It will
 throw the network error. When this happens you'll want to have an
@@ -9,6 +10,8 @@ Most likely you'll want to place one specficially for network errors at the same
 you put your `<Suspense>`. What you do with the error once you catch it, is of course
 up to you.
 
+## Error Boundary
+
 This library provides `NetworkErrorBoundary` component that only catches network
 errors and sends them to a fallback component you provide. Other errors will rethrow.
 
@@ -32,3 +35,9 @@ popup.
 
 Additionally you could also use one error boundary for any error
 type and handle network errors there.
+
+## Without Error Boundary
+
+Error boundaries provide elegant ways to reduce complexity by handling many
+errors in the react tree in one location. However, if you find yourself wanting to handle
+error state manually you can adapt the [useStatefulResource()](./no-suspense.md) hook.
diff --git a/website/i18n/en.json b/website/i18n/en.json
@@ -163,13 +163,15 @@
     "links": {
       "Getting Started": "Getting Started",
       "API": "API",
-      "Guides": "Guides",
+      "Resource Definitions": "Resource Definitions",
       "Github": "Github",
       "🎮 Demo": "🎮 Demo"
     },
     "categories": {
       "Getting Started": "Getting Started",
-      "Guides": "Guides",
+      "Basics": "Basics",
+      "Defining Network Interfaces": "Defining Network Interfaces",
+      "Advanced": "Advanced",
       "API": "API"
     }
   },

diff --git a/website/sidebars.json b/website/sidebars.json
@@ -4,37 +4,28 @@
       "getting-started/installation",
       "getting-started/usage"
     ],
-    "Guides": [
-      "guides/README",
-      {
-        "type": "subcategory",
-        "label": "Basics",
-        "ids": [
-          "guides/loading-state",
-          "guides/network-errors",
-          "guides/fetch-multiple",
-          "guides/pagination",
-          "guides/immutability",
-          "guides/mocking-unfinished"
-        ]
-      },
-      {
-        "type": "subcategory",
-        "label": "Defining your network interface",
-        "ids": [
-          "guides/resource-types",
-          "guides/computed-properties",
-          "guides/multi-pk",
-          "guides/network-transform",
-          "guides/auth",
-          "guides/jsonp",
-          "guides/custom-networking",
-          "guides/resource-lifetime"
-        ]
-      },
+    "Basics": [
+      "guides/loading-state",
+      "guides/network-errors",
+      "guides/fetch-multiple",
+      "guides/pagination",
+      "guides/immutability",
+      "guides/mocking-unfinished"
+    ],
+    "Defining Network Interfaces": [
+      "guides/resource-types",
+      "guides/computed-properties",
+      "guides/multi-pk",
+      "guides/network-transform",
+      "guides/auth",
+      "guides/jsonp",
+      "guides/custom-networking",
+      "guides/resource-lifetime"
+    ],
+    "Advanced": [
       {
         "type": "subcategory",
-        "label": "Performance Optimizations (optional)",
+        "label": "Performance Optimizations",
         "ids": ["guides/nested-response", "guides/rpc"]
       },
       {

diff --git a/website/siteConfig.js b/website/siteConfig.js
@@ -49,7 +49,7 @@ const siteConfig = {
   headerLinks: [
     { doc: 'getting-started/installation', label: 'Getting Started' },
     { doc: 'api/README', label: 'API' },
-    { doc: 'guides/README', label: 'Guides' },
+    { doc: 'guides/resource-types', label: 'Resource Definitions' },
     { href: 'https://www.github.com/coinbase/rest-hooks', label: 'Github' },
     { href: 'https://stackblitz.com/edit/rest-hooks', label: '🎮 Demo' },
     //{ page: 'help', label: 'Help' },