doc(orga): Add intro pages to connector, component and guides

Also:
 - auto generate the example page
 - fix some styling
 - moved guides into a folder

Fix #1468

docgen/layouts/common/header.pug

@@ -57,14 +57,14 @@
       li.cm-menu__list__item
         a(href=h.publicPath('gettingstarted.html')) Getting started
       li.cm-menu__list__item
-        a(href=h.publicPath('Styling.html')) Guide
+        a(href=h.publicPath('guides.html')) Guide
       li.cm-menu__list__item
         a(aria-controls='dropdown-2', aria-expanded='false', data-toggle-dropdown='dropdown-2') API <span class="glyph">&#x25BC;</span>
         ul#dropdown-2.simple-dropdown(role='tree', tabindex='-1')
           li
-            a(href=h.publicPath('component/InstantSearch.html'), role='treeitem') Components
+            a(href=h.publicPath('component.html'), role='treeitem') Components
           li
-            a(href=h.publicPath('HOC/Hits.html'), role='treeitem') Connector
+            a(href=h.publicPath('connector.html'), role='treeitem') Connector
 
 
       li.cm-menu__list__item

docgen/layouts/main-entry.pug

@@ -0,0 +1,9 @@
+extends archetypes/single-column-formatted.pug
+include mixins/nav-main.pug
+
+block content
+  .content
+    .documentation-section
+      div!=contents
+      h2 Table of content
+      +nav(navPath, navigation, title, headings)

docgen/layouts/mixins/nav-main.pug

@@ -0,0 +1,12 @@
+mixin nav(currentPath, navItems, title, headings)
+  ul.category-content
+    if navItems
+      +navRec(currentPath, navItems, title, 2)
+
+mixin navRec(currentPath, navItems, title, depth)
+  for navItem in navItems
+    - var isCurrentFile = navItem.path === currentPath;
+    - var className = ['sidebar-element', ('level-h' + depth), (isCurrentFile ? 'navItem-active' : 'navItem')];
+    - var activeClass = isCurrentFile ? 'navItem-active' : '';
+    li(class=className)
+      a(href=h.publicPath(navItem.path) class=activeClass)=navItem.title

docgen/plugins/navigation.js

@@ -7,7 +7,7 @@ export default function() {
     // First we scann all the HTML files to retrieve all the related documents based
     // on the category attribute in the metadata
     forEach(files, (data, path) => {
-      if (!path.match(/\.html$/)) return;
+      if (!path.match(/\.html$/) || data.tocVisibility === false) return;
       const category = data.category || 'other';
       categories[category] = categories[category] || [];
       categories[category].push({
@@ -26,7 +26,10 @@ export default function() {
       // than one without.
       // Then navigation is sorted by title.
       data.navigation = categories[category].sort((a, b) => {
-        if (a.navWeight === b.navWeight || a.navWeight === undefined || b.navWeight === undefined) {
+        if (a.title && b.title &&
+            (a.navWeight === b.navWeight ||
+            a.navWeight === undefined ||
+            b.navWeight === undefined)) {
           return a.title.localeCompare(b.title);
         } else {
           return b.navWeight - a.navWeight;

docgen/src/component.md

@@ -0,0 +1,18 @@
+---
+title: Components
+layout: main-entry.pug
+category: component
+tocVisibility: false
+---
+
+
+react-instantsearch provides a root component and widgets. The root component
+will provide the children a context to let them interact with Algolia. The
+widgets are the components who have the ability to interact with the context.
+
+## Widgets
+
+The widgets are plain components that are connected to the instantsearch context.
+To make this connection, they are wrapped using our collection of Higher Order
+Components that we call connectors.
+

docgen/src/connector.md

@@ -0,0 +1,16 @@
+---
+title: Connectors
+layout: main-entry.pug
+category: HOC
+tocVisibility: false
+---
+
+Connectors are higher order components. They encapsulate the logic for
+a specific kind of widget and they provide a way to interact with
+the instantsearch context.
+
+As higher order components, they have an outer component API that we call
+**exposed props** and they will provide some other props to the wrapped
+components which are called the **provided props**.
+
+Connectors are exposed so that you can create your own widgets very easily.

docgen/src/examples.md

@@ -1,11 +1,10 @@
 ---
 title: Examples
-layout: examples.pug
+layout: main-entry.pug
 category: examples
+tocVisibility: false
 ---
-# Examples
 
-* e-commerce: [live demo](examples/e-commerce/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/e-commerce)
-* tourism: [live demo](examples/tourism/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/tourism)
-* media: [live demo](examples/media/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/media)
-* Material-UI: [live demo](examples/material-ui/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/material-ui)
+To demonstrate the flexibility of react-instantsearch we have created some demos.
+If you think that there is a missing use-case don't hesitate to create an issue
+on [our github page](https://github.com/algolia/instantsearch.js/issues).

docgen/src/examples/e-commerce/index.html

@@ -2,8 +2,7 @@
 title: E-commerce
 layout: example.pug
 name: e-commerce
-nav_groups:
-  - examples
+category: examples
 stylesheets:
   - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css
   - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css

docgen/src/examples/material-ui/index.html

@@ -2,8 +2,7 @@
 title: Material-UI
 layout: example.pug
 name: material-ui
-nav_groups:
-  - examples
+category: examples
 stylesheets:
   - https://fonts.googleapis.com/icon?family=Material+Icons
 ---

docgen/src/examples/media/index.html

@@ -2,8 +2,7 @@
 title: Media
 layout: example.pug
 name: media
-nav_groups:
-  - examples
+category: examples
 stylesheets:
   - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css
   - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css

docgen/src/examples/tourism/index.html

@@ -2,8 +2,7 @@
 title: Tourism
 layout: example.pug
 name: tourism
-nav_groups:
-  - examples
+category: examples
 stylesheets:
   - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css
   - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css

docgen/src/guides.md

@@ -0,0 +1,11 @@
+---
+title: Guides
+layout: main-entry.pug
+category: guide
+tocVisibility: false
+---
+
+In order to complete your knowledge of react-instantsearch, we wrote a series
+of guides. Each guide covers a specific subject from a pratical point of view.
+
+If you think that a subject is not covered [drop us an issue on github](https://github.com/algolia/instantsearch.js/issues).

docgen/src/stylesheets/components/_documentation.scss

@@ -1,15 +1,18 @@
 .documentation-section {
-  padding-bottom: 200px;
-
   .container {
-
     article {
       width: 100%;
       position: relative;
       margin-top: 60px;
     }
   }
 
+  p,
+  ul,
+  ol {
+    font-size: 16px;
+    line-height: 22px;
+  }
 
   h2 {
     color: $charcoal-grey;
@@ -76,6 +79,7 @@
     width: calc(100% - #{$sidebar-width});
     padding-left: 30px;
     padding-top: 120px;
+    padding-bottom: 200px;
 
     p,
     ul,