Adds graph spec; some housekeeping.

diff --git a/docs/internals/dataset-spec.yaml b/docs/internals/specs/dataset-spec.yaml
similarity index 96%
rename from docs/internals/dataset-spec.yaml
rename to docs/internals/specs/dataset-spec.yaml
index 7679ca0..47fc0b7 100644 (file)
--- a/docs/internals/dataset-spec.yaml
+++ b/docs/internals/specs/dataset-spec.yaml
@@ -1,10 +1,10 @@
-###  Kraken Datasource Spec  ###
-
-# Describes the format of datasource json/yaml files for use in the Kraken chart UI.
+###  Limn Datasource Spec  ###
+# 
+# Describes the format of datasource json/yaml files for use in the Limn chart UI.
+# 
 # Reminder: the project transparently compiles any .yaml files requested as .json
 # at request time -- you're welcome to generate them in either form.
-
-# TODO: Thrift/Avro schema
+# TODO: Thrift/Avro schema?
 
 
 id        : Unique identifier for this datasource. This file should be named `{id}.{ext}`

diff --git a/docs/internals/specs/graph-spec.yaml b/docs/internals/specs/graph-spec.yaml
new file mode 100644 (file)
index 0000000..3069622
--- /dev/null
+++ b/docs/internals/specs/graph-spec.yaml
@@ -0,0 +1,52 @@
+###  Graph Spec  ###
+# 
+# Describes the format of graph json/yaml files saved by the Limn framework.
+
+
+id        : Unique identifier for this graph. This file will be named {id}.json
+            and live in the data directory alongside the data file. Defaults to the slug.
+slug      : Unique identifier used in URLs for the graph.
+
+name      : Human-friendly name given to the graph.
+shortName : A shorter version of the graph name for use in the UI.
+desc      : Description of the graph.
+
+
+width     : Width in pixels of the graph, or "auto" to fit to 100% of the container.
+height    : Height in pixels of the graph, or "auto" to fit to 100% of the container.
+parents   : Array of graph-ids from which to inherit values.
+
+### Metadata about the Data Sources and Metrics
+data:
+    palette: Name of a color palette to use to generate new default colors for columns.
+    # Metrics is an array of Metric objects, matching the description below
+    metrics:
+        label           : Human-readable label for this metric. If empty, defaults to the column
+                          label for the datasource.
+        type            : DataType for this column -- usually "int".
+        disabled        : Whether this metric is disabled. Disabled metrics behave exactly like
+                          deleted/non-existant metrics, except that they still appear in the dataset UI.
+        timespan :
+            start : Start of the data, eg: 2012/01/01T00:00:00 or 2012/01/01 or 1325404800
+                    All dates should be seconds-since-the-epoch, or ISO-8601 formatted: YYYY/MM/DDThh:mm:ss.s
+                    See also: http://www.w3.org/TR/NOTE-datetime
+                    And: http://blog.dygraphs.com/2012/03/javascript-and-dates-what-mess.html
+            end   : End of the data, eg: 2012/02/01T00:00:00 or 2012/02/01 or 1328083200
+            step  : Amount of time between elapsed between each row, measured in seconds, eg: 86400
+        
+        # DataSource
+        source_id        : Identifier for the datasource that backs this metric.
+        source_col       : Column in the datasource that backs this metric.
+        
+        # Chart Options
+        color            : Color of the line in the chart.
+        visible          : Whether this metric begins hidden in the display.
+        format_value     : Format string or method to use to format displayed metric values.
+        format_axis      : Format string or method to use to format displayed metric values in the axis.
+        
+        transforms       : List of transforms to apply to the data before display.
+        scale            : Scaling factor for this metric (a shortcut for transforming the data).
+
+### Defaults for charting
+chartType : Visualization library to use. Valid: "dygraphs".
+options   : Dict of chart option names to values.

diff --git a/docs/internals/vis-editor.md b/docs/internals/vis-editor.md
deleted file mode 100644 (file)
index 5c6a335..0000000
--- a/docs/internals/vis-editor.md
+++ /dev/null
@@ -1,2 +0,0 @@
-# Visualization Editor
-

diff --git a/docs/internals/d3-mvc.md b/docs/notes/d3-mvc.md
similarity index 100%
rename from docs/internals/d3-mvc.md
rename to docs/notes/d3-mvc.md

diff --git a/docs/internals/housekeeping.md b/docs/notes/housekeeping.md
similarity index 100%
rename from docs/internals/housekeeping.md
rename to docs/notes/housekeeping.md

diff --git a/docs/notes.md b/docs/notes/notes.md
similarity index 100%
rename from docs/notes.md
rename to docs/notes/notes.md

diff --git a/docs/notes/tag-notes.md b/docs/notes/option-tag-notes.md
similarity index 100%
rename from docs/notes/tag-notes.md
rename to docs/notes/option-tag-notes.md