Add optional documentation.

README.md

@@ -6,35 +6,32 @@ a configuration file, specified through a GET parameter, that contains a descrip
 ```javascript
 {
   "sort-options": {
-    "values": ["Impact", "Popularity", "Median (ms)", "75% (ms)"],
-    "selected": "Impact"
-  },
+      "values": ["Estimate (ms)", "Add-on", "Frequency (%)"],
+      "selected": "Estimate (ms)"
+    },
   "filter-options": [
-    {"id": "Application",
-     "values": ["", "Firefox", "Fennec"],
-     "selected": ""},
-    {"id": "Platform",
-     "values": ["", "WINNT", "Linux", "Darwin", "Android"],
-     "selected": ""},
-    {"id": "Measure",
-     "values": ["", "startup_MS", "shutdown_MS"],
-     "selected": ""},
-    {"id": "Limit",
-     "values": [10, 25, 100],
-     "selected": 10}
-  ],
-  "title": ["Telemetry Add-on Performance", "Bootstrap add-on start up and shut down times"],
-  "primary-key": ["Application", "Platform", "Addon ID", "Version", "Measure"],
-  "header": ["Application", "Platform", "Addon ID", "Version", "Name", "Measure",
-             "Sessions", "Popularity", "Impact", "Median (ms)", "75% (ms)", "95% (ms)"],
-  "url-prefix": "https://s3-us-west-2.amazonaws.com/telemetry-public-analysis/addon_perf/data/weekly_addons"
+      {"id": "Limit",
+       "values": [25, 50, 100, 200, 500],
+       "selected": 25
+      }
+    ],
+  "title": ["Add-ons startup correlations", "Correlations between startup time and add-ons"],
+  "description": ["A linear regression model is fit using the add-ons as predictors for the startup time. The job is run weekly on all the data collected on Monday for the release channel on Windows.",
+                  "http://robertovitillo.com/2014/10/07/using-ml-to-correlate-add-ons-to-performance-bottlenecks/"],
+  "primary-key": ["Add-on"],
+  "header": ["Add-on", "Frequency (%)", "Estimate (ms)", "Error (ms)", "t-statistic"],
+  "field-description": ["The name of the add-on", "The fraction of pings that contained the add-on", "The add-on coefficient expresses the effect of the addon on startup time wrt the average startup time without any add-ons", "The standard error of the coefficient", "The value of the associated t-statistic for the coefficient"],
+  "url-prefix": "https://s3-us-west-2.amazonaws.com/telemetry-public-analysis/addon_analysis/data/startup_addon_summary"
 }
 ```
 
 Where
 - `sort-options` specifies the fields the dashboard should allow sorting on;
 - `filter-options` is a list of filter descriptors which specifiy the filterable columns and the allowed values to filter on;
-- `primary-keys` is the collection of fields that constitute the primary key which is used to identify uniquely a row;
+- `primary-key` is the collection of fields that constitute the primary key which is used to identify uniquely a row;
+- `description` is the overall description of the dashboard with an optional URL that links to the code or blogpost (optional);
+- `header` is the list of column headers (optional);
+- `field-description` is a list of descriptions of the column headers;
 - `url-prefix` is the url prefix that the dashboard uses to concatenate the date of the requested dataset.
 
 The filename for a dataset of a given week should follow the pattern: `url-prefix20140804.csv.gz`, where `20140804` is the date of the Monday of the requested week.

src/dashgen/core.cljs

@@ -85,6 +85,29 @@
                        (str title " ")
                        (dom/small nil subtitle))))))
 
+(defn header-description-widget [[description link] owner]
+  (println link)
+  (reify
+    om/IRender
+    (render [_]
+      (dom/h5 nil
+              description
+              (when link (dom/span nil
+                                   " "
+                                   (dom/a #js {:href link} "More information")
+                                   "."))))))
+
+(defn header-field-description-widget [{:keys [header field-description]} owner]
+  (reify
+    om/IRender
+    (render [_]
+      (let [doc (map #(str %1 ": " %2) header field-description)]
+        (dom/div nil
+                 (dom/h5 nil "Field documentation:")
+                 (dom/div nil
+                          (apply dom/ul nil
+                                 (map (partial dom/li nil) doc))))))))
+
 (defn body-toolbar-widget [{:keys [base-date throbber]} owner]
   (reify
     om/IRender
@@ -146,6 +169,14 @@
           (dom/div #js {:className "container"}
                    (om/build header-title-widget
                              (:title app))
+                   (when (:description app)
+                     (om/build header-description-widget
+                               (:description app)))
+                   (when (:field-description app)
+                     (om/build header-field-description-widget
+                               {:header (:header app)
+                                :field-description (:field-description app)}))
+                   (when (or (:description app) (:field-description app)) (dom/hr nil))
                    (om/build header-toolbar-widget
                              {:filter-options (:filter-options app)
                               :sort-options (:sort-options app)