Documenting the library in the README. Adding example images.

jasongilman · Jan 14, 2016 · 84dd3f8 · 84dd3f8
1 parent b772d0c
commit 84dd3f8
Show file tree

Hide file tree

Showing 8 changed files with 121 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,122 @@
 # proto-repl-charts package
 
-TODO documentation
+Proto REPL Charts is an Atom plugin that extends [Proto REPL](https://github.com/jasongilman/proto-repl) and allows you to display tables and graphs of results from executed Clojure Code.
+
+## Example
+
+Execute this in Proto REPL:
+
+```Clojure
+(require 'prc)
+
+(prc/line-chart
+ "Trigonometry"
+ {"sin" (map #(Math/sin %) (range 0.0 6.0 0.2))
+  "cos" (map #(Math/cos %) (range 0.0 6.0 0.2))})
+```
+
+... and display this:
+
+![A screenshot of Proto REPL Charts showing a graph with sine and cosine](https://github.com/jasongilman/proto-repl-charts/raw/master/front_image.png)
+
+## Installation
+
+1. Install [Proto REPL](https://github.com/jasongilman/proto-repl#installation).
+2. `apm install proto-repl-charts` or go to your Atom settings, select "+ Install" and search for "proto-repl-charts".
+
+## Usage
+
+Proto REPL Charts are invoked from Clojure code run in Proto REPL. A very small Clojure library, proto-repl-charts, defines a namespace `prc` with functions for displaying different charts.
+
+1. Add proto-repl-charts as a dependency in your Clojure project.
+
+Add `[proto-repl-charts "0.1.0"]` to your dependencies in your `project.clj` file.
+
+(Proto REPL comes with a default Clojure project. If you bring open a new Atom window for and start a REPL it will already have proto-repl-charts dependency loaded and available.)
+
+2. [Start the REPL in Proto REPL](https://github.com/jasongilman/proto-repl#usage) and wait for it to come up.
+
+3. Execute one of the functions in the `prc` namespace. See the examples below for specific examples
+
+The `prc` chart functions are all of the form `(prc/<function-name> <tab-name> <series-map> <[options]>)`
+
+* `function-name` - the name of the function to invoke
+* `tab-name` - is the name of the chart to put in the Atom tab. Repeated execution will replace the chart in the tab with the matching name.
+* `series-map` - should be a map of series names to a sequence of values for that series. For example `{"alpha" [1 2 3], "beta" [2 4 5]}` would display two series named alpha and beta with the values 1, 2, and 3 for alpha and 2, 4, and 5 for beta.
+* `options` - an optional map of display options. The only option supported right now is `:labels` which is a list of labels. The index of the label in the list corresponds to the index of the values in the series.
+
+### Displaying a Line Chart
+
+```Clojure
+(let [input-values (range 0.0 6.0 0.5)]
+  (prc/line-chart
+   "Trigonometry"
+   {"sin" (map #(Math/sin %) input-values)
+    "cos" (map #(Math/cos %) input-values)}
+   {:labels input-values}))
+```
+
+![line chart](https://github.com/jasongilman/proto-repl-charts/raw/master/examples/line_chart.png)
+
+### Displaying a Bar Chart
+
+```Clojure
+(prc/bar-chart
+  "GDP_By_Year"
+  {"2013" [16768 9469 4919 3731]
+   "2014" [17418 10380 4616 3859]}
+  {:labels ["US" "China" "Japan" "Germany"]})
+```
+
+![bar chart](https://github.com/jasongilman/proto-repl-charts/raw/master/examples/bar_chart.png)
+
+### Displaying a Scatter Chart
+
+```Clojure
+(let [tlr (java.util.concurrent.ThreadLocalRandom/current)]
+  (prc/scatter-chart
+   "Randoms"
+   {:gaussian (repeatedly 200 #(.nextGaussian tlr))
+    :uniform  (repeatedly 200 #(.nextDouble tlr))}))
+```
+
+![scatter chart](https://github.com/jasongilman/proto-repl-charts/raw/master/examples/scatter_chart.png)
+
+### Displaying a Custom Chart
+
+Displays a custom chart in a tab with the given name. [C3](http://c3js.org/) is the charting library used. The chart config will be converted from Clojure to a JavaScript object and passed to C3. It can be any configuration data C3 supports. See [C3 examples](http://c3js.org/examples.html) for more.
+
+```Clojure
+(prc/custom-chart
+  "Custom"
+  {:data {:columns
+          [["data1" 30 20 50 40 60 50]
+           ["data2" 200 130 90 240 130 220]
+           ["data3" 300 200 160 400 250 250]
+           ["data4" 200 130 90 240 130 220]
+           ["data5" 130 120 150 140 160 150]
+           ["data6" 90 70 20 50 60 120]]
+          :type "bar"
+          :types {:data3 "spline"
+                  :data4 "line"
+                  :data6 "area"}
+          :groups [["data1" "data2"]]}})
+```
+
+![custom chart](https://github.com/jasongilman/proto-repl-charts/raw/master/examples/custom_chart.png)
+
+### Displaying a Table
+
+Proto REPL Charts can display a table of data that can be sorted by individual columns. The row data can either be a sequence of sequences or a sequence of maps.
+
+```Clojure
+(prc/table
+  "Users"
+  [{:name "Jane" :age 24 :favorite-color :blue}
+   {:name "Matt" :age 28 :favorite-color :red}
+   {:name "Austin" :age 56 :favorite-color :green}
+   {:name "Lisa" :age 32 :favorite-color :green}
+   {:name "Peter" :age 32 :favorite-color :green}])
+```
+
+![table from maps](https://github.com/jasongilman/proto-repl-charts/raw/master/examples/table_from_maps.png)
diff --git a/examples/bar_chart.png b/examples/bar_chart.png
diff --git a/examples/custom_chart.png b/examples/custom_chart.png
diff --git a/examples/line_chart.png b/examples/line_chart.png
diff --git a/examples/scatter_chart.png b/examples/scatter_chart.png
diff --git a/examples/table_from_maps.png b/examples/table_from_maps.png
diff --git a/front_image.png b/front_image.png
diff --git a/proto-repl-charts/project.clj b/proto-repl-charts/project.clj
@@ -1,4 +1,4 @@
-(defproject proto-repl-charts "0.1.0-SNAPSHOT"
+(defproject proto-repl-charts "0.1.0"
   :description "Defines helper functions for displaying graphs and tables in Proto REPL."
   :url "https://github.com/jasongilman/proto-repl-charts"
   :license {:name "MIT"