Merge branch 'scratchy'

Gruntfile.js

@@ -8,6 +8,7 @@ module.exports = function (grunt) {
     srcDir: 'src',
     destDir: 'dist',
     tempDir: 'tmp',
+    docsDir: 'docs/'
   };
 
   // load plugins

docs/kibana/configuration/config.js.asciidoc

@@ -0,0 +1,29 @@
+== Configuration ==
+config.js is where you will find the core Kibana configuration. This file contains parameter that
+must be set before kibana is run for the first time.
+// src/config.js:1
+
+=== Parameters ===
+// src/config.js:10
+
+==== elasticsearch ====
+
+The URL to your elasticsearch server. You almost certainly don't
+want +http://localhost:9200+ here. Even if Kibana and Elasticsearch are on
+the same host. By default this will attempt to reach ES at the same host you have
+elasticsearch installed on. You probably want to set it to the FQDN of your
+elasticsearch host
+// src/config.js:15
+
+==== kibana-int ====
+
+The default ES index to use for storing Kibana specific object
+such as stored dashboards
+// src/config.js:26
+
+==== panel_name ====
+
+An array of panel modules available. Panels will only be loaded when they are defined in the
+dashboard, but this list is used in the "add panel" interface.
+// src/config.js:34
+

docs/kibana/index.asciidoc

@@ -0,0 +1,18 @@
+= Kibana
+
+// Why can't I have a preamble here?
+
+== Introduction
+
+Kibana is an open source (Apache Licensed), browser based analytics and search dashboard for
+ElasticSearch. Kibana is a snap to setup and start using. Written entirely in HTML and Javascript
+it requires only a plain webserver, Kibana requires no fancy server side components.
+Kibana strives to be easy to get started with, while also being flexible and powerful, just like
+Elasticsearch.
+
+include::configuration/config.js.asciidoc[]
+
+include::panels.asciidoc[]
+
+// src/app/controllers/dash.js:1
+

docs/kibana/panels.asciidoc

@@ -0,0 +1,64 @@
+[[panels]]
+= Panels
+
+[partintro]
+--
+*Kibana* dashboards are made up of blocks called +panels+. Panels are organized into rows
+and can serve many purposes, though most are designed to provide the results of a query or
+multiple queries as a visualization. Other panels may show collections of documents or
+allow you to insert instructions for your users.
+
+Panels can be configured easily via the Kibana web interface. For more advanced usage, such
+as templated or scripted dashboards, documentation of panel properties is available in this
+section. You may find settings here which are not exposed via the web interface.
+
+Each panel type has its own properties, hover there are several that are shared.
+
+// src/app/controllers/row.js:61
+
+span:: A number, 1-12, that describes the width of the panel.
+// src/app/controllers/row.js:87
+
+editable:: Enable or disable the edit button the the panel
+// src/app/controllers/row.js:91
+
+type:: The type of panel this object contains. Each panel type will require additional
+properties. See the panel types list to the right.
+// src/app/controllers/row.js:95
+
+--
+// src/app/controllers/row.js:103
+
+include::panels/bettermap.asciidoc[]
+// src/app/panels/bettermap/module.js:1
+
+include::panels/column.asciidoc[]
+// src/app/panels/column/module.js:1
+
+include::panels/histogram.asciidoc[]
+// src/app/panels/histogram/module.js:1
+
+include::panels/hits.asciidoc[]
+// src/app/panels/hits/module.js:1
+
+include::panels/map.asciidoc[]
+// src/app/panels/map/module.js:1
+
+include::panels/pie.asciidoc[]
+// src/app/panels/pie/module.js:1
+
+include::panels/sparklines.asciidoc[]
+// src/app/panels/sparklines/module.js:1
+
+include::panels/table.asciidoc[]
+// src/app/panels/table/module.js:1
+
+include::panels/terms.asciidoc[]
+// src/app/panels/terms/module.js:1
+
+include::panels/text.asciidoc[]
+// src/app/panels/text/module.js:1
+
+include::panels/trends.asciidoc[]
+// src/app/panels/trends/module.js:1
+

docs/kibana/panels/bettermap.asciidoc

@@ -0,0 +1,36 @@
+== Bettermap
+Status: *Experimental*
+
+Bettermap is called bettermap for lack of a better name. Bettermap uses geographic coordinates to
+create clusters of markers on map and shade them orange, yellow and green depending on the
+density of the cluster.
+
+To drill down, click on a cluster. The map will be zoomed and the cluster broken into smaller cluster.
+When it no longer makes visual sense to cluster, individual markers will be displayed. Hover over
+a marker to see the tooltip value/
+
+IMPORTANT: bettermap requires an internet connection to download its map panels.
+// src/app/panels/bettermap/module.js:5
+
+=== Parameters
+
+field:: The field that contains the coordinates, in geojson format. GeoJSON is
++[longitude,latitude]+ in an array. This is different from most implementations, which use
+latitude, longitude.
+// src/app/panels/bettermap/module.js:62
+
+size:: The number of documents to use when drawing the map
+// src/app/panels/bettermap/module.js:70
+
+spyable:: Should the `inspect` icon be shown?
+// src/app/panels/bettermap/module.js:74
+
+tooltip:: Which field to use for the tooltip when hovering over a marker
+// src/app/panels/bettermap/module.js:78
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/bettermap/module.js:82
+

docs/kibana/panels/column.asciidoc

@@ -0,0 +1,14 @@
+== Column
+Status: *Stable*
+
+A pseudo panel that lets you add other panels to be arranged in a column with defined heights.
+While the column panel is stable, it does have many limitations, including the inability to drag
+and drop panels within its borders. It may be removed in a future release.
+
+// src/app/panels/column/module.js:5
+
+=== Parameters
+
+panel:: An array of panel objects
+// src/app/panels/column/module.js:36
+

docs/kibana/panels/histogram.asciidoc

@@ -0,0 +1,129 @@
+== Histogram
+Status: *Stable*
+
+The histogram panel allow for the display of time charts. It includes several modes and tranformations
+to display event counts, mean, min, max and total of numeric fields, and derivatives of counter
+fields.
+
+// src/app/panels/histogram/module.js:5
+
+=== Parameters
+==== Axis options
+mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be
+defined. Possible values: count, mean, max, min, total.
+// src/app/panels/histogram/module.js:65
+
+time_field:: x-axis field. This must be defined as a date type in Elasticsearch.
+// src/app/panels/histogram/module.js:72
+
+value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric.
+// src/app/panels/histogram/module.js:76
+
+x-axis:: Show the x-axis
+// src/app/panels/histogram/module.js:80
+
+y-axis:: Show the y-axis
+// src/app/panels/histogram/module.js:84
+
+scale:: Scale the y-axis by this factor
+// src/app/panels/histogram/module.js:88
+
+y_as_bytes:: Show the y-axis scale as bytes, automatically round to KB, MB, GB, etc.
+// src/app/panels/histogram/module.js:92
+
+==== Annotations
+annotate object:: A query can be specified, the results of which will be displayed as markers on
+the chart. For example, for noting code deploys.
+annotate.enable::: Should annotations, aka markers, be shown?
+annotate.query::: Lucene query_string syntax query to use for markers.
+annotate.size::: Max number of markers to show
+annotate.field::: Field from documents to show
+annotate.sort::: Sort array in format [field,order], For example [`@timestamp',`desc']
+// src/app/panels/histogram/module.js:115
+
+==== Interval options
+auto_int:: Automatically scale intervals?
+// src/app/panels/histogram/module.js:132
+
+resolution:: If auto_int is true, shoot for this many bars.
+// src/app/panels/histogram/module.js:137
+
+interval:: If auto_int is set to false, use this as the interval.
+// src/app/panels/histogram/module.js:141
+
+interval:: Array of possible intervals in the *View* selector. Example [`auto',`1s',`5m',`3h']
+// src/app/panels/histogram/module.js:145
+
+==== Drawing options
+lines:: Show line chart
+// src/app/panels/histogram/module.js:149
+
+fill:: Area fill factor for line charts, 1-10
+// src/app/panels/histogram/module.js:154
+
+linewidth:: Weight of lines in pixels
+// src/app/panels/histogram/module.js:158
+
+points:: Show points on chart
+// src/app/panels/histogram/module.js:162
+
+pointradius:: Size of points in pixels
+// src/app/panels/histogram/module.js:166
+
+bars:: Show bars on chart
+// src/app/panels/histogram/module.js:170
+
+stack:: Stack multiple series
+// src/app/panels/histogram/module.js:174
+
+spyable:: Show inspect icon
+// src/app/panels/histogram/module.js:178
+
+zoomlinks:: Show `Zoom Out' link
+// src/app/panels/histogram/module.js:182
+
+options:: Show quick view options section
+// src/app/panels/histogram/module.js:186
+
+legend:: Display the legond
+// src/app/panels/histogram/module.js:190
+
+show_query:: If no alias is set, should the query be displayed?
+// src/app/panels/histogram/module.js:194
+
+interactive:: Enable click-and-drag to zoom functionality
+// src/app/panels/histogram/module.js:198
+
+legend_counts:: Show counts in legend
+// src/app/panels/histogram/module.js:202
+
+==== Transformations
+timezone:: Correct for browser timezone?. Valid values: browser, utc
+// src/app/panels/histogram/module.js:206
+
+percentage:: Show the y-axis as a percentage of the axis total. Only makes sense for multiple
+queries
+// src/app/panels/histogram/module.js:211
+
+zerofill:: Improves the accuracy of line charts at a small performance cost.
+// src/app/panels/histogram/module.js:216
+
+derivative:: Show each point on the x-axis as the change from the previous point
+// src/app/panels/histogram/module.js:220
+
+tooltip object::
+tooltip.value_type::: Individual or cumulative controls how tooltips are display on stacked charts
+tooltip.query_as_alias::: If no alias is set, should the query be displayed?
+// src/app/panels/histogram/module.js:224
+
+grid object:: Min and max y-axis values
+grid.min::: Minimum y-axis value
+grid.max::: Maximum y-axis value
+// src/app/panels/histogram/module.js:96
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/histogram/module.js:105
+

docs/kibana/panels/hits.asciidoc

@@ -0,0 +1,37 @@
+== Hits
+Status: *Stable*
+
+The hits panel displays the number of hits for each of the queries on the dashboard in a
+configurable format specified by the `chart' property.
+
+// src/app/panels/hits/module.js:5
+
+=== Parameters
+
+arrangement:: The arrangement of the legend. horizontal or vertical
+// src/app/panels/hits/module.js:49
+
+chart:: bar, pie or none
+// src/app/panels/hits/module.js:55
+
+counter_pos:: The position of the legend, above or below
+// src/app/panels/hits/module.js:59
+
+donut:: If the chart is set to pie, setting donut to true will draw a hole in the midle of it
+// src/app/panels/hits/module.js:63
+
+tilt:: If the chart is set to pie, setting tilt to true will tilt it back into an oval
+// src/app/panels/hits/module.js:67
+
+labels:: If the chart is set to pie, setting labels to true will draw labels in the slices
+// src/app/panels/hits/module.js:71
+
+spyable:: Setting spyable to false disables the inspect icon.
+// src/app/panels/hits/module.js:75
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/hits/module.js:79
+

docs/kibana/panels/map.asciidoc

@@ -0,0 +1,32 @@
+== Map
+Status: *Stable*
+
+The map panel translates 2 letter country or state codes into shaded regions on a map. Currently
+available maps are world, usa and europe.
+
+// src/app/panels/map/module.js:5
+
+=== Parameters
+
+map:: Map to display. world, usa, europe
+// src/app/panels/map/module.js:48
+
+colors:: An array of colors to use to shade the map. If 2 colors are specified, shades
+between them will be used. For example [`#A0E2E2', `#265656']
+// src/app/panels/map/module.js:54
+
+size:: Max number of regions to shade
+// src/app/panels/map/module.js:59
+
+exclude:: exclude this array of regions. For example [`US',`BR',`IN']
+// src/app/panels/map/module.js:63
+
+spyable:: Setting spyable to false disables the inspect icon.
+// src/app/panels/map/module.js:67
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/map/module.js:71
+

docs/kibana/panels/pie.asciidoc

@@ -0,0 +1,50 @@
+== Pie
+Status: *Deprecated*
+
+The pie panel has been largely replaced by the +terms+ panel. It exists for backwards compatibility
+for now, but will be removed in a future release
+
+// src/app/panels/pie/module.js:5
+
+=== Parameters
+
+mode:: terms or goal. Terms mode finds the top N most popular terms, Goal mode display
+progress towards a fix goal in terms of documents matched
+// src/app/panels/pie/module.js:48
+
+size:: The max number of results to display in +terms+ mode.
+// src/app/panels/pie/module.js:55
+
+exclude:: Exclude these terms in terms mode
+// src/app/panels/pie/module.js:59
+
+donut:: Draw a hole in the middle of the pie, creating a tasty donut.
+// src/app/panels/pie/module.js:63
+
+tilt:: Tilt the pie back into an oval shape
+// src/app/panels/pie/module.js:67
+
+legend:: The location of the legend, above, below or none
+// src/app/panels/pie/module.js:71
+
+labels:: Set to false to disable drawing labels inside the pie slices
+// src/app/panels/pie/module.js:75
+
+spyable:: Set to false to disable the inspect function.
+// src/app/panels/pie/module.js:79
+
+==== Query
+
+query object:: This confusingly named object has properties to set the terms mode field,
+and the fixed goal for the goal mode
+query.field::: the field to facet on in terms mode
+query.goal::: the fixed goal for goal mode
+// src/app/panels/pie/module.js:83
+
+==== Queries
+
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/pie/module.js:92
+

docs/kibana/panels/sparklines.asciidoc

@@ -0,0 +1,32 @@
+== Sparklines
+Status: *Experimental*
+
+The sparklines panel shows tiny time charts. The purpose of these is not to give an exact value,
+but rather to show the shape of the time series in a compact manner
+
+// src/app/panels/sparklines/module.js:5
+
+=== Parameters
+mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be
+defined. Possible values: count, mean, max, min, total.
+// src/app/panels/sparklines/module.js:56
+
+time_field:: x-axis field. This must be defined as a date type in Elasticsearch.
+// src/app/panels/sparklines/module.js:62
+
+value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric.
+// src/app/panels/sparklines/module.js:66
+
+interval:: Sparkline intervals are computed automatically as long as there is a time filter
+present. In the absence of a time filter, use this interval.
+// src/app/panels/sparklines/module.js:70
+
+spyable:: Show inspect icon
+// src/app/panels/sparklines/module.js:75
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/sparklines/module.js:79
+

docs/kibana/panels/table.asciidoc

@@ -0,0 +1,63 @@
+== table
+Status: *Stable*
+
+The table panel contains a sortable, pagable view of documents that. It can be arranged into
+defined columns and offers several interactions, such as performing adhoc terms aggregations.
+
+// src/app/panels/table/module.js:5
+
+=== Parameters
+
+size:: The number of hits to show per page
+// src/app/panels/table/module.js:53
+
+pages:: The number of pages available
+// src/app/panels/table/module.js:59
+
+offset:: The current page
+// src/app/panels/table/module.js:63
+
+sort:: An array describing the sort order of the table. For example [`@timestamp',`desc']
+// src/app/panels/table/module.js:67
+
+overflow:: The css overflow property. `min-height' (expand) or `auto' (scroll)
+// src/app/panels/table/module.js:71
+
+fields:: the fields used a columns of the table, in an array.
+// src/app/panels/table/module.js:75
+
+highlight:: The fields on which to highlight, in an array
+// src/app/panels/table/module.js:79
+
+sortable:: Set sortable to false to disable sorting
+// src/app/panels/table/module.js:83
+
+header:: Set to false to hide the table column names
+// src/app/panels/table/module.js:87
+
+paging:: Set to false to hide the paging controls of the table
+// src/app/panels/table/module.js:91
+
+field_list:: Set to false to hide the list of fields. The user will be able to expand it,
+but it will be hidden by default
+// src/app/panels/table/module.js:95
+
+all_fields:: Set to true to show all fields in the mapping, not just the current fields in
+the table.
+// src/app/panels/table/module.js:100
+
+trimFactor:: The trim factor is the length at which to truncate fields takinging into
+consideration the number of columns in the table. For example, a trimFactor of 100, with 5
+columns in the table, would trim each column at 20 character. The entirety of the field is
+still available in the expanded view of the event.
+// src/app/panels/table/module.js:105
+
+spyable:: Set to false to disable the inspect icon
+// src/app/panels/table/module.js:112
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/table/module.js:116
+

docs/kibana/panels/terms.asciidoc

@@ -0,0 +1,56 @@
+== terms
+Status: *Stable*
+
+A table, bar chart or pie chart based on the results of an Elasticsearch terms facet.
+
+// src/app/panels/terms/module.js:5
+
+=== Parameters
+
+field:: The field on which to computer the facet
+// src/app/panels/terms/module.js:45
+
+exclude:: terms to exclude from the results
+// src/app/panels/terms/module.js:51
+
+missing:: Set to false to disable the display of a counter showing how much results are
+missing the field
+// src/app/panels/terms/module.js:55
+
+other:: Set to false to disable the display of a counter representing the aggregate of all
+values outside of the scope of your +size+ property
+// src/app/panels/terms/module.js:60
+
+size:: Show this many terms
+// src/app/panels/terms/module.js:65
+
+order:: count, term, reverse_count or reverse_term
+// src/app/panels/terms/module.js:69
+
+donut:: In pie chart mode, draw a hole in the middle of the pie to make a tasty donut.
+// src/app/panels/terms/module.js:74
+
+tilt:: In pie chart mode, tilt the chart back to appear as more of an oval shape
+// src/app/panels/terms/module.js:78
+
+lables:: In pie chart mode, draw labels in the pie slices
+// src/app/panels/terms/module.js:82
+
+arrangement:: In bar or pie mode, arrangement of the legend. horizontal or vertical
+// src/app/panels/terms/module.js:86
+
+chart:: table, bar or pie
+// src/app/panels/terms/module.js:90
+
+counter_pos:: The location of the legend in respect to the chart, above or below.
+// src/app/panels/terms/module.js:94
+
+spyable:: Set spyable to false to disable the inspect button
+// src/app/panels/terms/module.js:98
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/terms/module.js:102
+

docs/kibana/panels/text.asciidoc

@@ -0,0 +1,16 @@
+== text
+Status: *Stable*
+
+The text panel is used for displaying static text formated as markdown, sanitized html or as plain
+text.
+
+// src/app/panels/text/module.js:5
+
+=== Parameters
+
+mode:: `html', `markdown' or `text'
+// src/app/panels/text/module.js:33
+
+content:: The content of your panel, written in the mark up specified in +mode+
+// src/app/panels/text/module.js:39
+

docs/kibana/panels/trends.asciidoc

@@ -0,0 +1,27 @@
+== trends
+Status: *Beta*
+
+A stock-ticker style representation of how queries are moving over time. For example, if the
+time is 1:10pm, your time picker was set to "Last 10m", and the "Time Ago" parameter was set to
+"1h", the panel would show how much the query results have changed since 12:00-12:10pm
+
+// src/app/panels/trends/module.js:5
+
+=== Parameters
+
+ago:: A date math formatted string describing the relative time period to compare the
+queries to.
+// src/app/panels/trends/module.js:49
+
+arrangement:: `horizontal' or `vertical'
+// src/app/panels/trends/module.js:56
+
+spyable:: Set to false to disable the inspect icon
+// src/app/panels/trends/module.js:60
+
+==== Queries
+queries object:: This object describes the queries to use on this panel.
+queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+queries.ids::: In +selected+ mode, which query ids are selected.
+// src/app/panels/trends/module.js:64
+

package.json

@@ -29,7 +29,8 @@
     "grunt-contrib-uglify": "~0.2.4",
     "load-grunt-tasks": "~0.2.0",
     "glob": "~3.2.7",
-    "grunt-contrib-connect": "~0.5.0"
+    "grunt-contrib-connect": "~0.5.0",
+    "grunt-scratchy": "git://github.com/rashidkpc/grunt-scratchy.git"
   },
   "license": "Apache License"
 }

src/app/controllers/dash.js

@@ -1,3 +1,22 @@
+/** @scratch /index/0
+ * = Kibana
+ *
+ * // Why can't I have a preamble here?
+ *
+ * == Introduction
+ *
+ * Kibana is an open source (Apache Licensed), browser based analytics and search dashboard for
+ * ElasticSearch. Kibana is a snap to setup and start using. Written entirely in HTML and Javascript
+ * it requires only a plain webserver, Kibana requires no fancy server side components.
+ * Kibana strives to be easy to get started with, while also being flexible and powerful, just like
+ * Elasticsearch.
+ *
+ * include::configuration/config.js.asciidoc[]
+ *
+ * include::panels.asciidoc[]
+ *
+ */
+
 define([
   'angular',
   'config',

src/app/controllers/row.js

@@ -58,6 +58,25 @@ function (angular, app, _) {
         $scope.row.panels.push(panel);
       };
 
+      /** @scratch /panels/0
+       * [[panels]]
+       * = Panels
+       *
+       * [partintro]
+       * --
+       * *Kibana* dashboards are made up of blocks called +panels+. Panels are organized into rows
+       * and can serve many purposes, though most are designed to provide the results of a query or
+       * multiple queries as a visualization. Other panels may show collections of documents or
+       * allow you to insert instructions for your users.
+       *
+       * Panels can be configured easily via the Kibana web interface. For more advanced usage, such
+       * as templated or scripted dashboards, documentation of panel properties is available in this
+       * section. You may find settings here which are not exposed via the web interface.
+       *
+       * Each panel type has its own properties, hover there are several that are shared.
+       *
+      */
+
       $scope.reset_panel = function(type) {
         var
           defaultSpan = 4,
@@ -65,12 +84,26 @@ function (angular, app, _) {
 
         $scope.panel = {
           error   : false,
+          /** @scratch /panels/1
+           * span:: A number, 1-12, that describes the width of the panel.
+           */
           span    : _as < defaultSpan && _as > 0 ? _as : defaultSpan,
+          /** @scratch /panels/1
+           * editable:: Enable or disable the edit button the the panel
+           */
           editable: true,
+          /** @scratch /panels/1
+           * type:: The type of panel this object contains. Each panel type will require additional
+           * properties. See the panel types list to the right.
+           */
           type    : type
         };
       };
 
+      /** @scratch /panels/2
+       * --
+       */
+
       $scope.init();
 
     }

src/app/panels/bettermap/module.js

@@ -1,13 +1,21 @@
-/*
-
-  ## Better maps
-
-  ### Parameters
-  * size :: How many results to show, more results = slower
-  * field :: field containing a 2 element array in the format [lon,lat]
-  * tooltip :: field to extract the tool tip value from
-  * spyable :: Show the 'eye' icon that reveals the last ES query
-*/
+/** @scratch /panels/5
+ * include::panels/bettermap.asciidoc[]
+ */
+
+/** @scratch /panels/bettermap/0
+ * == Bettermap
+ * Status: *Experimental*
+ *
+ * Bettermap is called bettermap for lack of a better name. Bettermap uses geographic coordinates to
+ * create clusters of markers on map and shade them orange, yellow and green depending on the
+ * density of the cluster.
+ *
+ * To drill down, click on a cluster. The map will be zoomed and the cluster broken into smaller cluster.
+ * When it no longer makes visual sense to cluster, individual markers will be displayed. Hover over
+ * a marker to see the tooltip value/
+ *
+ * IMPORTANT: bettermap requires an internet connection to download its map panels.
+ */
 define([
   'angular',
   'app',
@@ -51,21 +59,43 @@ function (angular, app, _, L, localRequire) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/bettermap/3
+       * === Parameters
+       *
+       * field:: The field that contains the coordinates, in geojson format. GeoJSON is
+       * +[longitude,latitude]+ in an array. This is different from most implementations, which use
+       * latitude, longitude.
+       */
+      field   : null,
+      /** @scratch /panels/bettermap/5
+       * size:: The number of documents to use when drawing the map
+       */
+      size    : 1000,
+      /** @scratch /panels/bettermap/5
+       * spyable:: Should the `inspect` icon be shown?
+       */
+      spyable : true,
+      /** @scratch /panels/bettermap/5
+       * tooltip:: Which field to use for the tooltip when hovering over a marker
+       */
+      tooltip : "_id",
+      /** @scratch /panels/bettermap/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
       },
-      size    : 1000,
-      spyable : true,
-      tooltip : "_id",
-      field   : null
     };
 
     _.defaults($scope.panel,_d);
-    $scope.requireContext = localRequire;
 
     // inorder to use relative paths in require calls, require needs a context to run. Without
     // setting this property the paths would be relative to the app not this context/file.
+    $scope.requireContext = localRequire;
 
     $scope.init = function() {
       $scope.$on('refresh',function(){
@@ -204,6 +234,7 @@ function (angular, app, _, L, localRequire) {
                 zoom: 10
               });
 
+              // This could be made configurable?
               L.tileLayer('http://{s}.tile.cloudmade.com/57cbb6ca8cac418dbb1a402586df4528/22677/256/{z}/{x}/{y}.png', {
                 maxZoom: 18,
                 minZoom: 2

src/app/panels/column/module.js

@@ -1,11 +1,16 @@
-/*
-
-  ## Column
-
-  ### Parameters
-  * panels :: an array of panel objects. All of their spans should be set to 12
-
-*/
+/** @scratch /panels/5
+ * include::panels/column.asciidoc[]
+ */
+
+/** @scratch /panels/column/0
+ * == Column
+ * Status: *Stable*
+ *
+ * A pseudo panel that lets you add other panels to be arranged in a column with defined heights.
+ * While the column panel is stable, it does have many limitations, including the inability to drag
+ * and drop panels within its borders. It may be removed in a future release.
+ *
+ */
 define([
   'angular',
   'app',
@@ -28,6 +33,11 @@ function (angular, app, _, config) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/column/3
+       * === Parameters
+       *
+       * panel:: An array of panel objects
+       */
       panels : []
     };
     _.defaults($scope.panel,_d);

src/app/panels/histogram/module.js

@@ -1,32 +1,16 @@
-/*
-
-  ## Histogram
-
-  ### Parameters
-  * auto_int :: Auto calculate data point interval?
-  * resolution ::  If auto_int is enables, shoot for this many data points, rounding to
-                    sane intervals
-  * interval :: Datapoint interval in elasticsearch date math format (eg 1d, 1w, 1y, 5y)
-  * fill :: Only applies to line charts. Level of area shading from 0-10
-  * linewidth ::  Only applies to line charts. How thick the line should be in pixels
-                  While the editor only exposes 0-10, this can be any numeric value.
-                  Set to 0 and you'll get something like a scatter plot
-  * timezone :: This isn't totally functional yet. Currently only supports browser and utc.
-                browser will adjust the x-axis labels to match the timezone of the user's
-                browser
-  * spyable ::  Dislay the 'eye' icon that show the last elasticsearch query
-  * zoomlinks :: Show the zoom links?
-  * bars :: Show bars in the chart
-  * stack :: Stack multiple queries. This generally a crappy way to represent things.
-             You probably should just use a line chart without stacking
-  * points :: Should circles at the data points on the chart
-  * lines :: Line chart? Sweet.
-  * legend :: Show the legend?
-  * x-axis :: Show x-axis labels and grid lines
-  * y-axis :: Show y-axis labels and grid lines
-  * interactive :: Allow drag to select time range
-
-*/
+/** @scratch /panels/5
+ * include::panels/histogram.asciidoc[]
+ */
+
+/** @scratch /panels/histogram/0
+ * == Histogram
+ * Status: *Stable*
+ *
+ * The histogram panel allow for the display of time charts. It includes several modes and tranformations
+ * to display event counts, mean, min, max and total of numeric fields, and derivatives of counter
+ * fields.
+ *
+ */
 define([
   'angular',
   'app',
@@ -78,12 +62,66 @@ function (angular, app, $, _, kbn, moment, timeSeries) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/histogram/3
+       * === Parameters
+       * ==== Axis options
+       * mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be
+       * defined. Possible values: count, mean, max, min, total.
+       */
       mode          : 'count',
+      /** @scratch /panels/histogram/3
+       * time_field:: x-axis field. This must be defined as a date type in Elasticsearch.
+       */
       time_field    : '@timestamp',
-      queries       : {
-        mode          : 'all',
-        ids           : []
+      /** @scratch /panels/histogram/3
+       * value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric.
+       */
+      value_field   : null,
+      /** @scratch /panels/histogram/3
+       * x-axis:: Show the x-axis
+       */
+      'x-axis'      : true,
+      /** @scratch /panels/histogram/3
+       * y-axis:: Show the y-axis
+       */
+      'y-axis'      : true,
+      /** @scratch /panels/histogram/3
+       * scale:: Scale the y-axis by this factor
+       */
+      scale         : 1,
+      /** @scratch /panels/histogram/3
+       * y_as_bytes:: Show the y-axis scale as bytes, automatically round to KB, MB, GB, etc.
+       */
+      y_as_bytes    : false,
+      /** @scratch /panels/histogram/5
+       * grid object:: Min and max y-axis values
+       * grid.min::: Minimum y-axis value
+       * grid.max::: Maximum y-axis value
+       */
+      grid          : {
+        max: null,
+        min: 0
       },
+      /** @scratch /panels/histogram/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      },
+      /** @scratch /panels/histogram/3
+       * ==== Annotations
+       * annotate object:: A query can be specified, the results of which will be displayed as markers on
+       * the chart. For example, for noting code deploys.
+       * annotate.enable::: Should annotations, aka markers, be shown?
+       * annotate.query::: Lucene query_string syntax query to use for markers.
+       * annotate.size::: Max number of markers to show
+       * annotate.field::: Field from documents to show
+       * annotate.sort::: Sort array in format [field,order], For example [`@timestamp',`desc']
+       */
       annotate      : {
         enable      : false,
         query       : "*",
@@ -91,40 +129,106 @@ function (angular, app, $, _, kbn, moment, timeSeries) {
         field       : '_type',
         sort        : ['_score','desc']
       },
-      value_field   : null,
+      /** @scratch /panels/histogram/3
+       * ==== Interval options
+       * auto_int:: Automatically scale intervals?
+       */
       auto_int      : true,
+      /** @scratch /panels/histogram/3
+       * resolution:: If auto_int is true, shoot for this many bars.
+       */
       resolution    : 100,
+      /** @scratch /panels/histogram/3
+       * interval:: If auto_int is set to false, use this as the interval.
+       */
       interval      : '5m',
+      /** @scratch /panels/histogram/3
+       * interval:: Array of possible intervals in the *View* selector. Example [`auto',`1s',`5m',`3h']
+       */
       intervals     : ['auto','1s','1m','5m','10m','30m','1h','3h','12h','1d','1w','1y'],
+      /** @scratch /panels/histogram/3
+       * ==== Drawing options
+       * lines:: Show line chart
+       */
+      lines         : false,
+      /** @scratch /panels/histogram/3
+       * fill:: Area fill factor for line charts, 1-10
+       */
       fill          : 0,
+      /** @scratch /panels/histogram/3
+       * linewidth:: Weight of lines in pixels
+       */
       linewidth     : 3,
+      /** @scratch /panels/histogram/3
+       * points:: Show points on chart
+       */
+      points        : false,
+      /** @scratch /panels/histogram/3
+       * pointradius:: Size of points in pixels
+       */
       pointradius   : 5,
-      timezone      : 'browser', // browser, utc or a standard timezone
-      spyable       : true,
-      zoomlinks     : true,
+      /** @scratch /panels/histogram/3
+       * bars:: Show bars on chart
+       */
       bars          : true,
+      /** @scratch /panels/histogram/3
+       * stack:: Stack multiple series
+       */
       stack         : true,
-      points        : false,
-      lines         : false,
+      /** @scratch /panels/histogram/3
+       * spyable:: Show inspect icon
+       */
+      spyable       : true,
+      /** @scratch /panels/histogram/3
+       * zoomlinks:: Show `Zoom Out' link
+       */
+      zoomlinks     : true,
+      /** @scratch /panels/histogram/3
+       * options:: Show quick view options section
+       */
+      options       : true,
+      /** @scratch /panels/histogram/3
+       * legend:: Display the legond
+       */
       legend        : true,
+      /** @scratch /panels/histogram/3
+       * show_query:: If no alias is set, should the query be displayed?
+       */
       show_query    : true,
+      /** @scratch /panels/histogram/3
+       * interactive:: Enable click-and-drag to zoom functionality
+       */
+      interactive   : true,
+      /** @scratch /panels/histogram/3
+       * legend_counts:: Show counts in legend
+       */
       legend_counts : true,
-      'x-axis'      : true,
-      'y-axis'      : true,
+      /** @scratch /panels/histogram/3
+       * ==== Transformations
+       * timezone:: Correct for browser timezone?. Valid values: browser, utc
+       */
+      timezone      : 'browser', // browser or utc
+      /** @scratch /panels/histogram/3
+       * percentage:: Show the y-axis as a percentage of the axis total. Only makes sense for multiple
+       * queries
+       */
       percentage    : false,
+      /** @scratch /panels/histogram/3
+       * zerofill:: Improves the accuracy of line charts at a small performance cost.
+       */
       zerofill      : true,
-      interactive   : true,
-      options       : true,
+      /** @scratch /panels/histogram/3
+       * derivative:: Show each point on the x-axis as the change from the previous point
+       */
       derivative    : false,
-      scale         : 1,
-      y_as_bytes    : false,
+      /** @scratch /panels/histogram/3
+       * tooltip object::
+       * tooltip.value_type::: Individual or cumulative controls how tooltips are display on stacked charts
+       * tooltip.query_as_alias::: If no alias is set, should the query be displayed?
+       */
       tooltip       : {
         value_type: 'cumulative',
         query_as_alias: true
-      },
-      grid          : {
-        max: null,
-        min: 0
       }
     };
 

src/app/panels/hits/module.js

@@ -1,16 +1,15 @@
-/*
-
-  ## Hits
-
-  ### Parameters
-  * style :: A hash of css styles
-  * arrangement :: How should I arrange the query results? 'horizontal' or 'vertical'
-  * chart :: Show a chart? 'none', 'bar', 'pie'
-  * donut :: Only applies to 'pie' charts. Punches a hole in the chart for some reason
-  * tilt :: Only 'pie' charts. Janky 3D effect. Looks terrible 90% of the time.
-  * lables :: Only 'pie' charts. Labels on the pie?
-
-*/
+/** @scratch /panels/5
+ * include::panels/hits.asciidoc[]
+ */
+
+/** @scratch /panels/hits/0
+ * == Hits
+ * Status: *Stable*
+ *
+ * The hits panel displays the number of hits for each of the queries on the dashboard in a
+ * configurable format specified by the `chart' property.
+ *
+ */
 define([
   'angular',
   'app',
@@ -46,18 +45,47 @@ define([
 
     // Set and populate defaults
     var _d = {
-      queries     : {
-        mode        : 'all',
-        ids         : []
-      },
       style   : { "font-size": '10pt'},
+      /** @scratch /panels/hits/3
+       * === Parameters
+       *
+       * arrangement:: The arrangement of the legend. horizontal or vertical
+       */
       arrangement : 'horizontal',
+      /** @scratch /panels/hits/3
+       * chart:: bar, pie or none
+       */
       chart       : 'bar',
+      /** @scratch /panels/hits/3
+       * counter_pos:: The position of the legend, above or below
+       */
       counter_pos : 'above',
+      /** @scratch /panels/hits/3
+       * donut:: If the chart is set to pie, setting donut to true will draw a hole in the midle of it
+       */
       donut   : false,
+      /** @scratch /panels/hits/3
+       * tilt:: If the chart is set to pie, setting tilt to true will tilt it back into an oval
+       */
       tilt    : false,
+      /** @scratch /panels/hits/3
+       * labels:: If the chart is set to pie, setting labels to true will draw labels in the slices
+       */
       labels  : true,
-      spyable : true
+      /** @scratch /panels/hits/3
+       * spyable:: Setting spyable to false disables the inspect icon.
+       */
+      spyable : true,
+      /** @scratch /panels/hits/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      },
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/map/module.js

@@ -1,19 +1,15 @@
-/*
-
-  ## Map
-
-  ### Parameters
-  * map :: 'world', 'us' or 'europe'
-  * colors :: an array of colors to use for the regions of the map. If this is a 2
-              element array, jquerymap will generate shades between these colors
-  * size :: How big to make the facet. Higher = more countries
-  * exclude :: Exlude the array of counties
-  * spyable :: Show the 'eye' icon that reveals the last ES query
-  * index_limit :: This does nothing yet. Eventually will limit the query to the first
-                   N indices
-
-*/
-
+/** @scratch /panels/5
+ * include::panels/map.asciidoc[]
+ */
+
+/** @scratch /panels/map/0
+ * == Map
+ * Status: *Stable*
+ *
+ * The map panel translates 2 letter country or state codes into shaded regions on a map. Currently
+ * available maps are world, usa and europe.
+ *
+ */
 define([
   'angular',
   'app',
@@ -49,16 +45,39 @@ function (angular, app, _, $) {
 
     // Set and populate defaults
     var _d = {
-      queries     : {
-        mode        : 'all',
-        ids         : []
-      },
+      /** @scratch /panels/map/3
+       * === Parameters
+       *
+       * map:: Map to display. world, usa, europe
+       */
       map     : "world",
+      /** @scratch /panels/map/3
+       * colors:: An array of colors to use to shade the map. If 2 colors are specified, shades
+       * between them will be used. For example [`#A0E2E2', `#265656']
+       */
       colors  : ['#A0E2E2', '#265656'],
+      /** @scratch /panels/map/3
+       * size:: Max number of regions to shade
+       */
       size    : 100,
+      /** @scratch /panels/map/3
+       * exclude:: exclude this array of regions. For example [`US',`BR',`IN']
+       */
       exclude : [],
+      /** @scratch /panels/map/3
+       * spyable:: Setting spyable to false disables the inspect icon.
+       */
       spyable : true,
-      index_limit : 0
+      /** @scratch /panels/map/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      }
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/pie/module.js

@@ -1,21 +1,15 @@
-/*
-
-  ## Pie
-
-  ### Parameters
-  * query :: An object with 2 possible parameters depends on the mode:
-  ** field: Fields to run a terms facet on. Only does anything in terms mode
-  ** goal: How many to shoot for, only does anything in goal mode
-  * exclude :: In terms mode, ignore these terms
-  * donut :: Drill a big hole in the pie
-  * tilt :: A janky 3D representation of the pie. Looks terrible 90% of the time.
-  * legend :: Show the legend?
-  * labels :: Label the slices of the pie?
-  * mode :: 'terms' or 'goal'
-  * default_field ::  LOL wat? A dumb fail over field if for some reason the query object
-                      doesn't have a field
-  * spyable :: Show the 'eye' icon that displays the last ES query for this panel
-*/
+/** @scratch /panels/5
+ * include::panels/pie.asciidoc[]
+ */
+
+/** @scratch /panels/pie/0
+ * == Pie
+ * Status: *Deprecated*
+ *
+ * The pie panel has been largely replaced by the +terms+ panel. It exists for backwards compatibility
+ * for now, but will be removed in a future release
+ *
+ */
 define([
   'angular',
   'app',
@@ -51,20 +45,63 @@ define([
 
     // Set and populate defaults
     var _d = {
-      query   : { field:"_type", goal: 100},
-      queries     : {
-        mode        : 'all',
-        ids         : []
-      },
+      /** @scratch /panels/pie/3
+       * === Parameters
+       *
+       * mode:: terms or goal. Terms mode finds the top N most popular terms, Goal mode display
+       * progress towards a fix goal in terms of documents matched
+       */
+      mode    : "terms",
+      /** @scratch /panels/pie/3
+       * size:: The max number of results to display in +terms+ mode.
+       */
       size    : 10,
+      /** @scratch /panels/pie/3
+       * exclude:: Exclude these terms in terms mode
+       */
       exclude : [],
+      /** @scratch /panels/pie/3
+       * donut:: Draw a hole in the middle of the pie, creating a tasty donut.
+       */
       donut   : false,
+      /** @scratch /panels/pie/3
+       * tilt:: Tilt the pie back into an oval shape
+       */
       tilt    : false,
+      /** @scratch /panels/pie/3
+       * legend:: The location of the legend, above, below or none
+       */
       legend  : "above",
+      /** @scratch /panels/pie/3
+       * labels:: Set to false to disable drawing labels inside the pie slices
+       */
       labels  : true,
-      mode    : "terms",
-      default_field : 'DEFAULT',
+      /** @scratch /panels/pie/3
+       * spyable:: Set to false to disable the inspect function.
+       */
       spyable : true,
+      /** @scratch /panels/pie/3
+       * ==== Query
+       *
+       * query object:: This confusingly named object has properties to set the terms mode field,
+       * and the fixed goal for the goal mode
+       * query.field::: the field to facet on in terms mode
+       * query.goal::: the fixed goal for goal mode
+       */
+      query   : { field:"_type", goal: 100},
+      /** @scratch /panels/pie/5
+       * ==== Queries
+       *
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      },
+      default_field : '_type',
+
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/sparklines/module.js

@@ -1,32 +1,15 @@
-/*
-
-  ## Histogram
-
-  ### Parameters
-  * auto_int :: Auto calculate data point interval?
-  * resolution ::  If auto_int is enables, shoot for this many data points, rounding to
-                    sane intervals
-  * interval :: Datapoint interval in elasticsearch date math format (eg 1d, 1w, 1y, 5y)
-  * fill :: Only applies to line charts. Level of area shading from 0-10
-  * linewidth ::  Only applies to line charts. How thick the line should be in pixels
-                  While the editor only exposes 0-10, this can be any numeric value.
-                  Set to 0 and you'll get something like a scatter plot
-  * timezone :: This isn't totally functional yet. Currently only supports browser and utc.
-                browser will adjust the x-axis labels to match the timezone of the user's
-                browser
-  * spyable ::  Dislay the 'eye' icon that show the last elasticsearch query
-  * zoomlinks :: Show the zoom links?
-  * bars :: Show bars in the chart
-  * stack :: Stack multiple queries. This generally a crappy way to represent things.
-             You probably should just use a line chart without stacking
-  * points :: Should circles at the data points on the chart
-  * lines :: Line chart? Sweet.
-  * legend :: Show the legend?
-  * x-axis :: Show x-axis labels and grid lines
-  * y-axis :: Show y-axis labels and grid lines
-  * interactive :: Allow drag to select time range
-
-*/
+/** @scratch /panels/5
+ * include::panels/sparklines.asciidoc[]
+ */
+
+/** @scratch /panels/sparklines/0
+ * == Sparklines
+ * Status: *Experimental*
+ *
+ * The sparklines panel shows tiny time charts. The purpose of these is not to give an exact value,
+ * but rather to show the shape of the time series in a compact manner
+ *
+ */
 define([
   'angular',
   'app',
@@ -70,15 +53,39 @@ function (angular, app, $, _, kbn, moment, timeSeries) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/sparklines/3
+       * === Parameters
+       * mode:: Value to use for the y-axis. For all modes other than count, +value_field+ must be
+       * defined. Possible values: count, mean, max, min, total.
+       */
       mode          : 'count',
+      /** @scratch /panels/sparklines/3
+       * time_field:: x-axis field. This must be defined as a date type in Elasticsearch.
+       */
       time_field    : '@timestamp',
-      queries       : {
-        mode          : 'all',
-        ids           : []
-      },
+      /** @scratch /panels/sparklines/3
+       * value_field:: y-axis field if +mode+ is set to mean, max, min or total. Must be numeric.
+       */
       value_field   : null,
+      /** @scratch /panels/sparklines/3
+       * interval:: Sparkline intervals are computed automatically as long as there is a time filter
+       * present. In the absence of a time filter, use this interval.
+       */
       interval      : '5m',
-      spyable       : true
+      /** @scratch /panels/sparklines/3
+       * spyable:: Show inspect icon
+       */
+      spyable       : true,
+      /** @scratch /panels/sparklines/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      },
     };
 
     _.defaults($scope.panel,_d);

src/app/panels/table/module.js

@@ -1,31 +1,21 @@
-/*
-
-  ## Table
-
-  ### Parameters
-  * size :: Number of events per page to show
-  * pages :: Number of pages to show. size * pages = number of cached events.
-             Bigger = more memory usage byh the browser
-  * offset :: Position from which to start in the array of hits
-  * sort :: An array with 2 elements. sort[0]: field, sort[1]: direction ('asc' or 'desc')
-  * style :: hash of css properties
-  * fields :: columns to show in table
-  * overflow :: 'height' or 'min-height' controls wether the row will expand (min-height) to
-                to fit the table, or if the table will scroll to fit the row (height)
-  * trimFactor :: If line is > this many characters, divided by the number of columns, trim it.
-  * sortable :: Allow sorting?
-  * spyable :: Show the 'eye' icon that reveals the last ES query for this panel
-
-*/
+/** @scratch /panels/5
+ * include::panels/table.asciidoc[]
+ */
+
+/** @scratch /panels/table/0
+ * == table
+ * Status: *Stable*
+ *
+ * The table panel contains a sortable, pagable view of documents that. It can be arranged into
+ * defined columns and offers several interactions, such as performing adhoc terms aggregations.
+ *
+ */
 define([
   'angular',
   'app',
   'underscore',
   'kbn',
   'moment',
-
-  // 'text!./pagination.html',
-  // 'text!partials/querySelect.html'
 ],
 function (angular, app, _, kbn, moment) {
   'use strict';
@@ -60,27 +50,81 @@ function (angular, app, _, kbn, moment) {
 
     // Set and populate defaults
     var _d = {
-      queries     : {
-        mode        : 'all',
-        ids         : []
-      },
+      /** @scratch /panels/table/5
+       * === Parameters
+       *
+       * size:: The number of hits to show per page
+       */
       size    : 100, // Per page
+      /** @scratch /panels/table/5
+       * pages:: The number of pages available
+       */
       pages   : 5,   // Pages available
+      /** @scratch /panels/table/5
+       * offset:: The current page
+       */
       offset  : 0,
+      /** @scratch /panels/table/5
+       * sort:: An array describing the sort order of the table. For example [`@timestamp',`desc']
+       */
       sort    : ['_score','desc'],
-      group   : "default",
-      style   : {'font-size': '9pt'},
+      /** @scratch /panels/table/5
+       * overflow:: The css overflow property. `min-height' (expand) or `auto' (scroll)
+       */
       overflow: 'min-height',
+      /** @scratch /panels/table/5
+       * fields:: the fields used a columns of the table, in an array.
+       */
       fields  : [],
+      /** @scratch /panels/table/5
+       * highlight:: The fields on which to highlight, in an array
+       */
       highlight : [],
+      /** @scratch /panels/table/5
+       * sortable:: Set sortable to false to disable sorting
+       */
       sortable: true,
+      /** @scratch /panels/table/5
+       * header:: Set to false to hide the table column names
+       */
       header  : true,
+      /** @scratch /panels/table/5
+       * paging:: Set to false to hide the paging controls of the table
+       */
       paging  : true,
+      /** @scratch /panels/table/5
+       * field_list:: Set to false to hide the list of fields. The user will be able to expand it,
+       * but it will be hidden by default
+       */
       field_list: true,
+      /** @scratch /panels/table/5
+       * all_fields:: Set to true to show all fields in the mapping, not just the current fields in
+       * the table.
+       */
       all_fields: false,
+      /** @scratch /panels/table/5
+       * trimFactor:: The trim factor is the length at which to truncate fields takinging into
+       * consideration the number of columns in the table. For example, a trimFactor of 100, with 5
+       * columns in the table, would trim each column at 20 character. The entirety of the field is
+       * still available in the expanded view of the event.
+       */
       trimFactor: 300,
+      /** @scratch /panels/table/5
+       * spyable:: Set to false to disable the inspect icon
+       */
+      spyable : true,
+      /** @scratch /panels/table/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      },
+      style   : {'font-size': '9pt'},
       normTimes : true,
-      spyable : true
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/terms/module.js

@@ -1,15 +1,14 @@
-/*
-  ## Terms
-
-  ### Parameters
-  * style :: A hash of css styles
-  * size :: top N
-  * arrangement :: How should I arrange the query results? 'horizontal' or 'vertical'
-  * chart :: Show a chart? 'none', 'bar', 'pie'
-  * donut :: Only applies to 'pie' charts. Punches a hole in the chart for some reason
-  * tilt :: Only 'pie' charts. Janky 3D effect. Looks terrible 90% of the time.
-  * lables :: Only 'pie' charts. Labels on the pie?
-*/
+/** @scratch /panels/5
+ * include::panels/terms.asciidoc[]
+ */
+
+/** @scratch /panels/terms/0
+ * == terms
+ * Status: *Stable*
+ *
+ * A table, bar chart or pie chart based on the results of an Elasticsearch terms facet.
+ *
+ */
 define([
   'angular',
   'app',
@@ -43,24 +42,73 @@ function (angular, app, _, $, kbn) {
 
     // Set and populate defaults
     var _d = {
-      queries     : {
-        mode        : 'all',
-        ids         : []
-      },
+      /** @scratch /panels/terms/5
+       * === Parameters
+       *
+       * field:: The field on which to computer the facet
+       */
       field   : '_type',
+      /** @scratch /panels/terms/5
+       * exclude:: terms to exclude from the results
+       */
       exclude : [],
+      /** @scratch /panels/terms/5
+       * missing:: Set to false to disable the display of a counter showing how much results are
+       * missing the field
+       */
       missing : true,
+      /** @scratch /panels/terms/5
+       * other:: Set to false to disable the display of a counter representing the aggregate of all
+       * values outside of the scope of your +size+ property
+       */
       other   : true,
+      /** @scratch /panels/terms/5
+       * size:: Show this many terms
+       */
       size    : 10,
+      /** @scratch /panels/terms/5
+       * order:: count, term, reverse_count or reverse_term
+       */
       order   : 'count',
       style   : { "font-size": '10pt'},
+      /** @scratch /panels/terms/5
+       * donut:: In pie chart mode, draw a hole in the middle of the pie to make a tasty donut.
+       */
       donut   : false,
+      /** @scratch /panels/terms/5
+       * tilt:: In pie chart mode, tilt the chart back to appear as more of an oval shape
+       */
       tilt    : false,
+      /** @scratch /panels/terms/5
+       * lables:: In pie chart mode, draw labels in the pie slices
+       */
       labels  : true,
+      /** @scratch /panels/terms/5
+       * arrangement:: In bar or pie mode, arrangement of the legend. horizontal or vertical
+       */
       arrangement : 'horizontal',
+      /** @scratch /panels/terms/5
+       * chart:: table, bar or pie
+       */
       chart       : 'bar',
+      /** @scratch /panels/terms/5
+       * counter_pos:: The location of the legend in respect to the chart, above or below.
+       */
       counter_pos : 'above',
-      spyable     : true
+      /** @scratch /panels/terms/5
+       * spyable:: Set spyable to false to disable the inspect button
+       */
+      spyable     : true,
+      /** @scratch /panels/terms/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
+      queries     : {
+        mode        : 'all',
+        ids         : []
+      },
     };
     _.defaults($scope.panel,_d);
 

src/app/panels/text/module.js

@@ -1,10 +1,15 @@
-/*
-  ## Text
-  ### Parameters
-  * mode :: 'text', 'html', 'markdown'
-  * content :: Content of the panel
-  * style :: Hash containing css properties
-*/
+/** @scratch /panels/5
+ * include::panels/text.asciidoc[]
+ */
+
+/** @scratch /panels/text/0
+ * == text
+ * Status: *Stable*
+ *
+ * The text panel is used for displaying static text formated as markdown, sanitized html or as plain
+ * text.
+ *
+ */
 define([
   'angular',
   'app',
@@ -25,8 +30,15 @@ function (angular, app, _, require) {
 
     // Set and populate defaults
     var _d = {
-      status  : "Stable",
-      mode    : "markdown",
+      /** @scratch /panels/text/5
+       * === Parameters
+       *
+       * mode:: `html', `markdown' or `text'
+       */
+      mode    : "markdown", // 'html','markdown','text'
+      /** @scratch /panels/text/5
+       * content:: The content of your panel, written in the mark up specified in +mode+
+       */
       content : "",
       style: {},
     };

src/app/panels/trends/module.js

@@ -1,13 +1,16 @@
-/*
-
-  ## Trends
-
-  ### Parameters
-  * style :: A hash of css styles
-  * arrangement :: How should I arrange the query results? 'horizontal' or 'vertical'
-  * ago :: Date math formatted time to look back
-
-*/
+/** @scratch /panels/5
+ * include::panels/trends.asciidoc[]
+ */
+
+/** @scratch /panels/trends/0
+ * == trends
+ * Status: *Beta*
+ *
+ * A stock-ticker style representation of how queries are moving over time. For example, if the
+ * time is 1:10pm, your time picker was set to "Last 10m", and the "Time Ago" parameter was set to
+ * "1h", the panel would show how much the query results have changed since 12:00-12:10pm
+ *
+ */
 define([
   'angular',
   'app',
@@ -43,14 +46,32 @@ function (angular, app, _, kbn) {
 
     // Set and populate defaults
     var _d = {
+      /** @scratch /panels/trends/5
+       * === Parameters
+       *
+       * ago:: A date math formatted string describing the relative time period to compare the
+       * queries to.
+       */
+      ago     : '1d',
+      /** @scratch /panels/trends/5
+       * arrangement:: `horizontal' or `vertical'
+       */
+      arrangement : 'vertical',
+      /** @scratch /panels/trends/5
+       * spyable:: Set to false to disable the inspect icon
+       */
+      spyable: true,
+      /** @scratch /panels/trends/5
+       * ==== Queries
+       * queries object:: This object describes the queries to use on this panel.
+       * queries.mode::: Of the queries available, which to use. Options: +all, pinned, unpinned, selected+
+       * queries.ids::: In +selected+ mode, which query ids are selected.
+       */
       queries     : {
         mode        : 'all',
         ids         : []
       },
       style   : { "font-size": '14pt'},
-      ago     : '1d',
-      arrangement : 'vertical',
-      spyable: true
     };
     _.defaults($scope.panel,_d);
 

src/config.js

@@ -1,36 +1,41 @@
-/**
- * These is the app's configuration, If you need to configure
- * the default dashboard, please see dashboards/default
+/** @scratch /configuration/config.js/1
+ * == Configuration ==
+ * config.js is where you will find the core Kibana configuration. This file contains parameter that
+ * must be set before kibana is run for the first time.
  */
 define(['settings'],
 function (Settings) {
   "use strict";
 
+  /** @scratch /configuration/config.js/2
+   * === Parameters ===
+   */
   return new Settings({
 
-    /**
-     * URL to your elasticsearch server. You almost certainly don't
-     * want 'http://localhost:9200' here. Even if Kibana and ES are on
-     * the same host
+    /** @scratch /configuration/config.js/5
+     * ==== elasticsearch ====
      *
-     * By default this will attempt to reach ES at the same host you have
+     * The URL to your elasticsearch server. You almost certainly don't
+     * want +http://localhost:9200+ here. Even if Kibana and Elasticsearch are on
+     * the same host. By default this will attempt to reach ES at the same host you have
      * elasticsearch installed on. You probably want to set it to the FQDN of your
      * elasticsearch host
-     * @type {String}
      */
     elasticsearch: "http://"+window.location.hostname+":9200",
 
-    /**
+    /** @scratch /configuration/config.js/5
+     * ==== kibana-int ====
+     *
      * The default ES index to use for storing Kibana specific object
      * such as stored dashboards
-     * @type {String}
      */
     kibana_index: "kibana-int",
 
-    /**
-     * Panel modules available. Panels will only be loaded when they are defined in the
+    /** @scratch /configuration/config.js/5
+     * ==== panel_name ====
+     *
+     * An array of panel modules available. Panels will only be loaded when they are defined in the
      * dashboard, but this list is used in the "add panel" interface.
-     * @type {Array}
      */
     panel_names: [
       'histogram',
@@ -40,11 +45,9 @@ function (Settings) {
       'filtering',
       'timepicker',
       'text',
-      'fields',
       'hits',
       'dashcontrol',
       'column',
-      'derivequeries',
       'trends',
       'bettermap',
       'query',

tasks/default_task.js

@@ -1,4 +1,4 @@
 // Lint and build CSS
 module.exports = function(grunt) {
-  grunt.registerTask('default', ['jshint:source', 'less:src']);
+  grunt.registerTask('default', ['docs','jshint:source', 'less:src']);
 };

tasks/docs_task.js

@@ -0,0 +1,4 @@
+// Lint and build CSS
+module.exports = function(grunt) {
+  grunt.registerTask('docs', ['clean:docs', 'scratchy:docs']);
+};

tasks/options/clean.js

@@ -2,5 +2,6 @@ module.exports = function(config) {
   return {
     on_start: ['<%= destDir %>', '<%= tempDir %>'],
     temp: ['<%= tempDir %>'],
+    docs: ['<%= docsDir %>']
   };
 };

tasks/options/scratchy.js

@@ -0,0 +1,13 @@
+module.exports = function(config) {
+  return {
+    docs: {
+      src: ['src/app/**/*.js','src/config.js'],
+      dest: config.docsDir+"/kibana",
+      options: {
+        unslash: true,
+        extension: '.asciidoc',
+        annotate: '// '
+      }
+    }
+  }
+};