DOC: refactor documentation [skip ci]

README.md

@@ -17,35 +17,41 @@ functions. [g.js](dist/g.js) is an un-minified version for debugging.
 
 Interactions:
 
-- [urlfilter.min.js](dist/urlfilter.min.js): URL filtering library
+- URL filtering: [urlfilter.min.js](dist/urlfilter.min.js)
     - [$.urlfilter](#urlfilter) changes URL query parameters when clicked. Used to filter data.
-    - [g1.url.parse](#urlparse) parses a URL into a structured object
-    - [g1.url.join](#urljoin) joins two URLs
-    - [g1.url.update](#urlupdate) updates a URL's query parameters
-- [urlchange.min.js](dist/urlchange.min.js): URL state change events
+    - [g1.url.parse](#g1urlparse) parses a URL into a structured object
+    - [url.join](#urljoin) joins two URLs
+    - [url.update](#urlupdate) updates a URL's query parameters
+- URL state change events: [urlchange.min.js](dist/urlchange.min.js)
     - [$.urlchange](#urlchange) listens to hash changes and routes events
-- [highlight.min.js](dist/highlight.min.js): highlighting library
+- Highlighting: [highlight.min.js](dist/highlight.min.js)
     - [$.highlight](#highlight) toggles classes on elements when clicked or hover
 
-Data components:
+Components:
 
-- [formhandler.min.js](dist/formhandler.min.js): Table renderer using [FormHandler](https://learn.gramener.com/guide/formhandler/)
+- Table renderer using [FormHandler](https://learn.gramener.com/guide/formhandler/): [formhandler.min.js](dist/formhandler.min.js)
     - [$.formhandler](#formhandler) renders a HTML table from a [FormHandler URL](https://learn.gramener.com/guide/formhandler/)
-- [leaflet.min.js](dist/leaflet.min.js): Leaflet utilities
+- Leaflet utilities: [leaflet.min.js](dist/leaflet.min.js)
     - [L.TopoJSON](#ltopojson) loads TopoJSON files just like GeoJSON. Requires [topojson](https://github.com/topojson/topojson)
+- Sand dance transitions: [sanddance.min.js](dist/sanddance.min.js)
+    - [g1.sanddance](#g1sanddance) moves DOM elements smoothly based on data
+- Map viewer component: [mapviewer.min.js](dist/mapviewer.min.js)
+    - [g1.mapviewer](#g1mapviewer) renders leaflet maps and simplifies adding layers from data
 
 Utilities:
 
-- [template.min.js](dist/template.min.js): template library
+- Template library: [template.min.js](dist/template.min.js)
     - [$.template](#template) renders lodash templates. Requires [lodash](https://lodash.com/)
-- [event.min.js](dist/event.min.js): event library
+- Event library: [event.min.js](dist/event.min.js)
     - [$.dispatch](#dispatch) is like [trigger](https://api.jquery.com/trigger/) but sends a native event (triggers non-jQuery events too)
-- [datafilter.min.js](dist/datafilter.min.js): filtering data library
-    - [g1.datafilter](#datafilter) filters the data based on the options
-- [types.min.js](dist/types.min.js): type detection library
-    - [g1.types](#types) returns the data types of columns in a DataFrames
+- Data filtering library: [datafilter.min.js](dist/datafilter.min.js)
+    - [g1.datafilter](#g1datafilter) filters the data based on the options
+- Type detection library: [types.min.js](dist/types.min.js)
+    - [g1.types](#g1types) returns the data types of columns in a DataFrames
 
-## $.urlfilter
+
+<!-- ----------------------------------------------------------------------- -->
+# $.urlfilter
 
 Example:
 
@@ -88,7 +94,7 @@ For example:
 </script>
 ```
 
-### $.urlfilter attributes
+## $.urlfilter attributes
 
 URLFilter triggers use these attributes:
 
@@ -115,16 +121,27 @@ URLFilter containers uses these attributes:
   every `.urlfilter` trigger.
 
 
-## url.parse
+## $.urlfilter events
+
+- `urlfilter` is fired on the trigger when the URL is changed.
+  Note: if the page is reloaded (e.g. if there is no `data-target=`),
+  the page is reloaded and the event is lost. Attributes:
+    - `url`: the new URL
+- `load` is fired on the target when the URL is loaded -- only if the `data-target=` is a selector. Attributes:
+    - `url`: the new URL
+
+
+<!-- ----------------------------------------------------------------------- -->
+# g1.url.parse
 
 `g1.url` provides URL manipulation utilities.
 
+## url attributes
+
 ```js
 var url = g1.url.parse("https://username:password@example.com:80/~folder/subfolder/filename.html?a=1&a=2&b=3%2E&d#hash")
 ```
 
-### url object attributes
-
 This parses the URL and returns an object with the following attributes matching `window.location`:
 
 | Attribute  | Value                              |
@@ -167,7 +184,7 @@ var url = g1.url.parse('?a=1&a=2&b=3%2E&d#hash')
 These attributes are **not mutable**. To change the URL, use
 [url.join](#urljoin) or [url.update](#urlupdate).
 
-### url object methods
+## url.toString
 
 The url object has a `.toString()` method that converts the object back into a
 string.
@@ -245,7 +262,8 @@ g1.url.parse('/?a=1&b=2&c=3&d=4')       // Update this URL
 // Returns /?b=3&c=3&c=6&d=7
 ```
 
-## Interaction conventions
+<!-- ----------------------------------------------------------------------- -->
+# Interaction conventions
 
 All interaction components use this naming convention:
 
@@ -271,17 +289,8 @@ function. For example, `<body data-selector=".link">` is the same as
 `$('body').urlfilter({selector: '.link'})`.
 
 
-### $.urlfilter events
-
-- `urlfilter` is fired on the trigger when the URL is changed.
-  Note: if the page is reloaded (e.g. if there is no `data-target=`),
-  the page is reloaded and the event is lost. Attributes:
-    - `url`: the new URL
-- `load` is fired on the target when the URL is loaded -- only if the `data-target=` is a selector. Attributes:
-    - `url`: the new URL
-
-
-## $.urlchange
+<!-- ----------------------------------------------------------------------- -->
+# $.urlchange
 
 $.urlchange triggers custom events when the URL changes. This makes it easy to
 build URL-driven applications.
@@ -333,7 +342,7 @@ Examples:
   - `.on('#?x', function(e, val) { val == '1' && e.vals == ['1', '2'] })`
   - The `#?x` event is fired since x has a new value
 
-### $.urlchange events
+## $.urlchange events
 
 - `#?` is fired when the URL hash changes. Event attributes are:
   - `hash`: a [g1.url.parse](#urlparse) object that holds the parsed URL hash
@@ -344,7 +353,8 @@ Examples:
   - `val`: the first value of `vals`.
 
 
-## $.dropdown
+<!-- ----------------------------------------------------------------------- -->
+# $.dropdown
 
 Dropdown component that integrates well with g1.urlfilter
 
@@ -411,7 +421,7 @@ To use bootstrap-select options, use `options:`
 ```
 
 
-### $.dropdown events
+## $.dropdown events
 - `load` is triggered after dropdown is rendered
 - `change` is triggered whenever dropdown value is changed
 
@@ -433,7 +443,7 @@ To use bootstrap-select options, use `options:`
 
 ```
 
-### $.dropdown options
+## $.dropdown options
 - `data`: Array of values.
 - `url`: End point that returns the `data`. If `data:` is also given, `data` takes priority.
 - `target`: defines how URL is updated. Can be `''` (Default), `#` or `pushState`
@@ -442,7 +452,8 @@ To use bootstrap-select options, use `options:`
 - `options`: Supports same options as [bootstrap-select options](https://silviomoreto.github.io/bootstrap-select/options/)
 
 
-## $.highlight
+<!-- ----------------------------------------------------------------------- -->
+# $.highlight
 
 Highlight elements when hovering on or clicking another element.
 
@@ -459,7 +470,7 @@ Example:
 </script>
 ```
 
-### $.highlight attributes
+## $.highlight attributes
 
 Highlight triggers use these attributes:
 
@@ -475,13 +486,14 @@ Highlight containers use these attributes:
 - `data-attr` is the attribute that defines classes to toggle. Default: `data-classes`
 - `data-classes=` is the same as specifiying the data-classes on every highlighter. Default: `active`
 
-### $.highlight events
+## $.highlight events
 
 - `highlight` is fired on the trigger when activated. Attributes:
     - `target`: elements that match the `data-target=` selector
 
 
-## types
+<!-- ----------------------------------------------------------------------- -->
+# g1.types
 
 `g1.types(data)` returns the column data types. For example:
 
@@ -493,7 +505,7 @@ var data = [
 g1.types(data)      // Returns {"a": "number", "b": "number", "c": "string", "d": "date", "e": "boolean"}
 ```
 
-### types options
+## g1.types options
 
 `types()` accepts 2 parameters:
 
@@ -522,7 +534,8 @@ Rules:
   - Else -> `string`
 
 
-## g1.datafilter
+<!-- ----------------------------------------------------------------------- -->
+# g1.datafilter
 
 `g1.datafilter(data, filters)` returns the filtered data based on the filters. While urlfilter on [$.formhandler](#formhandler) applies filtering on data server side, `datafilter` applies urlfilter on frontend loaded data.
 
@@ -602,7 +615,8 @@ g1.datafilter(data2, {
 
 [formhandler-filters]: https://learn.gramener.com/guide/formhandler/#formhandler-filters
 
-## $.formhandler
+<!-- ----------------------------------------------------------------------- -->
+# $.formhandler
 
 An interactive table component for [FormHandler][formhandler] data.
 
@@ -620,7 +634,7 @@ In the above example, `data-page-size="10"` over-rides `pageSize: 20`.
 
 [formhandler]: https://learn.gramener.com/guide/formhandler/
 
-### $.formhandler options
+## $.formhandler options
 
 The full list of options is below. Simple options can be specified as `data-` attributes as well.
 
@@ -762,7 +776,7 @@ Features to be implemented:
 - Full text search
 - URL targets other than '#', e.g. pushState
 
-### $.formhandler events
+## $.formhandler events
 
 - `load` is fired on the source when the template is rendered. Attributes:
     - `formdata`: the FormHandler data
@@ -774,7 +788,7 @@ Features to be implemented:
 
 - `editmode` is fired on the source when the Edit button is clicked and table changes to edit mode.
 
-### $.formhandler examples
+## $.formhandler examples
 
 Render a table using the FormHandler at `./data`:
 
@@ -885,9 +899,8 @@ In edit mode, show HTML input bindings like Dropdown, Datepicker, Number fields.
 </script>
 ```
 
-
-
-## $.template
+<!-- ----------------------------------------------------------------------- -->
+# $.template
 
 ```html
 <script type="text/html">Your platform is <%= navigator.userAgent %></script>
@@ -918,7 +931,7 @@ using as `.template({var1: value, var2: value, ...})`. For example:
 
 To re-render the template, run `.template(data)` again with different data.
 
-### $.template options
+## $.template options
 
 To re-use the template or render the same template on a different DOM node,
 run `.template(data, {target: selector})`. This allows you to declare templates
@@ -960,7 +973,7 @@ an existing target. For example:
 ```
 
 
-### $.template attributes
+## $.template attributes
 
 Template containers can have an `src=` attribute that loads the template from a file:
 
@@ -1009,7 +1022,7 @@ Or you can directly render templates using
 </script>
 ```
 
-### $.template events
+## $.template events
 
 - `template` is fired on the source when the template is rendered. Attributes:
     - `templatedata`: the passed data
@@ -1027,7 +1040,8 @@ $('script[type="text/html"]')
   .template()                         // Trigger the template AFTER binding the event handler
 ```
 
-## $.dispatch
+<!-- ----------------------------------------------------------------------- -->
+# $.dispatch
 
 Triggers a native JavaScript event. For example:
 
@@ -1038,7 +1052,7 @@ $('a.action').dispatch('click')
 sends a click to `a.action`. Like [$.trigger](https://api.jquery.com/trigger/),
 but this will fire non-jQuery event handlers as well.
 
-### $.dispatch options
+## $.dispatch options
 
 You can add an optional dict as the second parameter. It can have any
 [event properties](https://developer.mozilla.org/en-US/docs/Web/API/Event#Properties)
@@ -1055,7 +1069,8 @@ $('a.action').dispatch('click', {bubbles: true, cancelable: false})
 https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events
 
 
-## L.TopoJSON
+<!-- ----------------------------------------------------------------------- -->
+# L.TopoJSON
 
 ```js
 var layer = new L.TopoJSON(topojson_data).addTo(map)
@@ -1075,11 +1090,12 @@ $.get('topojson-file.json')
 ```
 
 
-## sanddance
+<!-- ----------------------------------------------------------------------- -->
+# g1.sanddance
 
 Transitions elements with flexible timing controls.
 
-### sanddance options
+## g1.sanddance options
 
 It accepts 2 parameters
 
@@ -1128,7 +1144,7 @@ var selection_filtered = g1.sanddance({fill: 'red'}, {duration: 100, filter: fun
 selection.call(selection_filtered)
 ```
 
-### sanddance.chain
+## g1.sanddance.chain
 
 To apply a sequence of sanddances one after another, use `g1.sanddance.chain`. For example:
 
@@ -1142,9 +1158,7 @@ selection.call(
 )
 ```
 
-### sanddance layouts
-
-#### 1. grid
+## g1.sanddance grid layout
 
 Returns a sanddance that moves elements into a grid. Usage:
 
@@ -1230,7 +1244,7 @@ selection.call(
 )
 ```
 
-#### 2. hexpack
+## g1.sanddance hexpack layout
 
 Returns a sanddance that moves elements into a hexpack. Usage:
 
@@ -1250,7 +1264,7 @@ selection.call(
 ```
 The values can also be specified as a scale config and the options definitions are same as grid.
 
-### sanddance methods
+## g1.sanddance methods
 
 `sanddance.update(new_attrs, new_options)` returns a new sanddance that updates
 the old `attrs` with `new_attrs` and the old `options` with `new_options`.
@@ -1265,7 +1279,7 @@ g1.sanddance({}, { delay: 100 }).update({}, { duration: 100 }),
 g1.sanddance({}, { duration: 100, delay: 100 })
 ```
 
-### sanddance events
+## g1.sanddance events
 
 These events are triggered by the sanddance object.
 
@@ -1285,7 +1299,8 @@ selection.call(
 )
 ```
 
-## g1.mapviewer
+<!-- ----------------------------------------------------------------------- -->
+# g1.mapviewer
 
 Mapviewer is an abstraction over [Leaflet](http://leafletjs.com/) that can
 create common GIS applications using configurations.
@@ -1506,7 +1521,7 @@ Drilldown feature example:
 
 **Note**: You can use `type: 'topojson'` when loading TopoJSON maps.
 
-### g1.mapviewer options
+## g1.mapviewer options
 
 - `id`: ID of the map DOM element (example: `mapid`), or the DOM element
 - `map`:
@@ -1587,19 +1602,20 @@ Drilldown feature example:
     - `shapePadding`: padding of legend cell. Default `20`
     - `labelOffset`: value to determine distance of label from each legend cell. Default `20`
 
-### g1.mapviewer methods
+## g1.mapviewer methods
 `fitToLayer(layerName, options)`
 Zooms map view to fit the layer. Supports same options as [fitBounds options](http://leafletjs.com/reference-1.3.0.html#fitbounds-options)
 
 `zoomHandler(layerName, minZoomLevel, maxZoomLevel(optional) )`
 Shows the layer with `layerName` only between `minZoomLevel` and `maxZoomLevel`.
 
-### g1.mapviewer events
+## g1.mapviewer events
 
 - `layersloaded` is fired when all layers are saved in mapviewer.gLayers (used interally).
   - tooltip is rendered on each layer only after `layersload` is fired
 - `layerName + 'loaded'` is fired for each layer with name as `layerName`
 
+<!-- ----------------------------------------------------------------------- -->
 ## Contributing
 
 Contributions are welcome.