changes to getting started and introduction

uber · Jul 8, 2017 · ea4933a · ea4933a
1 parent 400b042
commit ea4933a
Show file tree

Hide file tree

Showing 9 changed files with 311 additions and 141 deletions.
diff --git a/docs/docs-app/constants/pages.js b/docs/docs-app/constants/pages.js
@@ -164,13 +164,58 @@ export const docPages = generatePath([
     name: 'Overview',
     pageType: 'documentation',
     children: [{
-      name: 'Getting started',
+      name: 'Introduction',
       content: {
-        markdown: getDocUrl('tutorials/getting-started.md'),
-        filename: 'tutorials/getting-started.md',
+        markdown: getDocUrl('introduction.md'),
+        filename: 'introduction.md',
+        pageType: 'documentation'
+      }
+    }
+    // , {
+    //  name: 'The Uber Visualization Suite',
+    //  content: {
+    //    markdown: getDocUrl('suite.md'),
+    //    filename: 'suite.md',
+    //    pageType: 'documentation'
+    // }
+    ]
+  },
+  {
+    name: 'Getting started',
+    pageType: 'documentation',
+    children: [{
+      name: 'React-vis in codepen',
+      content: {
+        markdown: getDocUrl('getting-started/react-vis-in-codepen.md'),
+        filename: 'getting-started/react-vis-in-codepen.md',
+        pageType: 'documentation'
+      }
+    }, {
+      name: 'Installing react-vis',
+      content: {
+        markdown: getDocUrl('getting-started/installing-react-vis.md'),
+        filename: 'getting-started/installing-react-vis.md',
+        pageType: 'documentation'
+      }
+    }, {
+      name: 'Creating a new react-vis project',
+      content: {
+        markdown: getDocUrl('getting-started/new-react-vis-project.md'),
+        filename: 'getting-started/new-react-vis-project.md',
         pageType: 'documentation'
       }
     }, {
+      name: 'Your first chart',
+      content: {
+        markdown: getDocUrl('getting-started/your-first-chart.md'),
+        filename: 'getting-started/your-first-chart.md',
+        pageType: 'documentation'
+      }
+    }]
+  }, {
+    name: 'General principles',
+    pageType: 'documentation',
+    children: [{
       name: 'Scales and data',
       content: {
         markdown: getDocUrl('scales-and-data.md'),
@@ -215,10 +260,10 @@ export const docPages = generatePath([
     }]
   },
   {
-    name: 'XY-Plot',
+    name: 'API Reference',
     children: [
       {
-        name: 'Introduction',
+        name: 'XY-Plot',
         content: {
           markdown: getDocUrl('xy-plot.md'),
           filename: 'xy-plot.md',
@@ -284,7 +329,7 @@ export const docPages = generatePath([
     ]
   },
   {
-    name: 'XY Plot Series',
+    name: 'Series reference',
     children: [
       {
         name: 'Arc Series',

diff --git a/docs/docs-app/stylesheets/table-of-contents.scss b/docs/docs-app/stylesheets/table-of-contents.scss
@@ -7,6 +7,8 @@
   width: 240px;
   z-index: 1;
 
+  min-height: calc(100vh - #{$topbar-height});
+
   >div {
     padding-bottom: 80px;
     padding-top: 20px;

diff --git a/docs/markdown/getting-started/getting-started.md b/docs/markdown/getting-started/getting-started.md
@@ -0,0 +1,120 @@
+### Getting started
+
+#### Jump right in on codepen!
+
+You can use react-vis directly on [codepen](https://codepen.io/ubervisualization/pen/BZOeZB) (or equivalent).  
+Each published version of react-vis is accessible via [unpkg.com](https://unpkg.com).
+
+Add react files, and a link to the latest react-vis version - such as https://unpkg.com/react-vis@1.6.7/dist/dist.min.js.
+
+But you can simply just use that [pen](https://codepen.io/ubervisualization/pen/BZOeZB) and take it from there.
+
+#### Install the react-vis module
+
+If you want to use react-vis in your project, add it from the command line: 
+
+```
+npm install react-vis
+```
+
+(or yarn add react-vis - the following will assume that you use npm for concision's sake but you can substitute yarn if installed)
+
+#### Create a new project with react-vis
+
+Let's create a new vis app from scratch.
+To do this, let's use [create-react-app](https://github.com/facebookincubator/create-react-app), the popular Facebook scaffold. 
+
+If you haven't installed yet, do so: 
+
+```
+npm install -g create-react-app
+```
+
+And now:
+```
+create-react-app my-awesome-vis-app
+cd my-awesome-vis-app
+npm install react-vis
+```
+
+That's it! you are now ready to create amazing charts. 
+
+Let's edit create-react-app's default App.js: 
+
+```jsx
+import React, { Component } from 'react';
+import './App.css';
+import '../node_modules/react-vis/dist/style.css';
+import {XYPlot, LineSeries} from 'react-vis';
+
+class App extends Component {
+  render() {
+    const data = [
+      {x: 0, y: 8},
+      {x: 1, y: 5},
+      {x: 2, y: 4},
+      {x: 3, y: 9},
+      {x: 4, y: 1},
+      {x: 5, y: 7},
+      {x: 6, y: 6},
+      {x: 7, y: 3},
+      {x: 8, y: 2},
+      {x: 9, y: 0}
+    ];
+    return (
+      <div className="App">
+        <XYPlot height={300} width={300}>
+          <LineSeries data={data} />
+        </XYPlot>
+      </div>
+    );
+  }
+}
+
+export default App;
+```
+
+and then on the command line interface:
+
+```
+npm run start
+```
+
+and your chart is in the browser. 
+
+Note that on line 3, I have imported the react-vis stylesheet. There are many ways to do that, and it is actually optional. But apps made with create-react-app will let you import stylesheets directly, so that's a simple way to do so.
+
+#### Your first chart
+
+We tried to make react-vis syntax as close to the traditional react syntax. You have components which have props and possibly children. 
+
+Every react-vis chart is inside a component called XYPlot, for which a height and a width must be specified:
+
+```jsx
+<XYPlot height={300} width = {300} />
+```
+
+And all the elements of a chart - series, axes, gridlines, etc. are other components, which will be children of XYPlot.
+
+```jsx
+<XYPlot height={300} width= {300}>
+  <VerticalGridLines />
+  <HorizontalGridLines />
+  <XAxis />
+  <YAxis />
+  <LineSeries data={data} />
+</XYPlot>
+```
+
+And like in traditional react, order matters as components are drawn in order. In the previous example, the gridlines are drawn below the line series, but in this next example, they will be drawn above it.
+
+```jsx
+<XYPlot height={300} width= {300}>
+  <LineSeries data={data} />
+  <VerticalGridLines />
+  <HorizontalGridLines />
+  <XAxis />
+  <YAxis />
+</XYPlot>
+```
+
diff --git a/docs/markdown/getting-started/installing-react-vis.md b/docs/markdown/getting-started/installing-react-vis.md
@@ -0,0 +1,9 @@
+### Install the react-vis module
+
+If you want to use react-vis in your project, add it from the command line: 
+
+```
+npm install react-vis
+```
+
+(or yarn add react-vis - the following will assume that you use npm for concision's sake but you can substitute yarn if installed)
diff --git a/docs/markdown/getting-started/new-react-vis-project.md b/docs/markdown/getting-started/new-react-vis-project.md
@@ -0,0 +1,64 @@
+### Create a new project with react-vis
+
+Let's create a new vis app from scratch.
+To do this, let's use [create-react-app](https://github.com/facebookincubator/create-react-app), the popular Facebook scaffold. 
+
+If you haven't installed yet, do so: 
+
+```
+npm install -g create-react-app
+```
+
+And now:
+```
+create-react-app my-awesome-vis-app
+cd my-awesome-vis-app
+npm install react-vis
+```
+
+That's it! you are now ready to create amazing charts. 
+
+Let's edit create-react-app's default App.js: 
+
+```jsx
+import React, { Component } from 'react';
+import './App.css';
+import '../node_modules/react-vis/dist/style.css';
+import {XYPlot, LineSeries} from 'react-vis';
+
+class App extends Component {
+  render() {
+    const data = [
+      {x: 0, y: 8},
+      {x: 1, y: 5},
+      {x: 2, y: 4},
+      {x: 3, y: 9},
+      {x: 4, y: 1},
+      {x: 5, y: 7},
+      {x: 6, y: 6},
+      {x: 7, y: 3},
+      {x: 8, y: 2},
+      {x: 9, y: 0}
+    ];
+    return (
+      <div className="App">
+        <XYPlot height={300} width={300}>
+          <LineSeries data={data} />
+        </XYPlot>
+      </div>
+    );
+  }
+}
+
+export default App;
+```
+
+and then on the command line interface:
+
+```
+npm run start
+```
+
+and your chart is in the browser. 
+
+Note that on line 3, I have imported the react-vis stylesheet. There are many ways to do that, and it is actually optional. But apps made with create-react-app will let you import stylesheets directly, so that's a simple way to do so.
diff --git a/docs/markdown/getting-started/react-vis-in-codepen.md b/docs/markdown/getting-started/react-vis-in-codepen.md
@@ -0,0 +1,8 @@
+### Jump right in on codepen!
+
+You can use react-vis directly on [codepen](https://codepen.io/ubervisualization/pen/BZOeZB) (or equivalent).  
+Each published version of react-vis is accessible via [unpkg.com](https://unpkg.com).
+
+Add react files, and a link to the latest react-vis version - such as https://unpkg.com/react-vis@1.6.7/dist/dist.min.js.
+
+But you can simply just use that [pen](https://codepen.io/ubervisualization/pen/BZOeZB) and take it from there.
diff --git a/docs/markdown/getting-started/your-first-chart.md b/docs/markdown/getting-started/your-first-chart.md
@@ -0,0 +1,46 @@
+### Your first chart
+
+We tried to make react-vis syntax as close to the traditional react syntax. You have components which have props and possibly children. 
+
+Every react-vis chart is inside a component called XYPlot, for which a height and a width must be specified:
+
+```jsx
+<XYPlot height={300} width = {300} />
+```
+
+And all the elements of a chart - series, axes, gridlines, etc. are other components, which will be children of XYPlot.
+
+```jsx
+const data = [
+  {x: 0, y: 8},
+  {x: 1, y: 5},
+  {x: 2, y: 4},
+  {x: 3, y: 9},
+  {x: 4, y: 1},
+  {x: 5, y: 7},
+  {x: 6, y: 6},
+  {x: 7, y: 3},
+  {x: 8, y: 2},
+  {x: 9, y: 0}
+];
+<XYPlot height={300} width= {300}>
+  <VerticalGridLines />
+  <HorizontalGridLines />
+  <XAxis />
+  <YAxis />
+  <LineSeries data={data} />
+</XYPlot>
+```
+
+And like in traditional react, order matters as components are drawn in order. In the previous example, the gridlines are drawn below the line series, but in this next example, they will be drawn above it.
+
+```jsx
+<XYPlot height={300} width= {300}>
+  <LineSeries data={data} />
+  <VerticalGridLines />
+  <HorizontalGridLines />
+  <XAxis />
+  <YAxis />
+</XYPlot>
+```
+
diff --git a/docs/markdown/introduction.md b/docs/markdown/introduction.md
@@ -0,0 +1,11 @@
+## react-vis
+
+react-vis is a charting library for React. 
+
+It is: 
+
+* __Expressive__: react-vis supports a large number of types of charts, from area charts to treemaps, as well as many charting elements like axes or tooltips. 
+* __High-level__: react-vis is optimized for making charts with the least amount of code. It lets user access high-level components rather than force them to control every pixel,
+* __Deeply customizable__: react-vis charts have sensible defaults, yet everything can be changed. 
+* __Consistent with React__: a chart in react-vis is made of components which have properties and children, just like traditional react,
+* __Industry-strong__: react-vis was created to support the many internal tools of Uber.