135 examples

.gitmodules

@@ -1,3 +1,7 @@
 [submodule "docs/_static/docson"]
 	path = docs/_static/docson
 	url = https://github.com/OpenDataServices/docson
+[submodule "flatten-tool"]
+	path = flatten-tool
+	url = https://github.com/OpenDataServices/flatten-tool/
+  branch = sheet-name-length

developer_docs.md

@@ -17,6 +17,7 @@ This section contains the following how-to guides:
 * [Deploy changes](#deploy-changes)
 * [Release a new version](#release-a-new-version)
 * [Update requirements](#update-requirements)
+* [Add an RDLS metadata example](#add-an-rdls-metadata-example)
 
 ### Propose changes
 
@@ -47,7 +48,7 @@ cd rdl-standard
 
 Subsequent instructions assume that your current working directory is `rdl-standard`, unless otherwise stated.
 
-#### Install submodules
+#### Update submodules
 
 ```bash
 git submodule init
@@ -106,6 +107,12 @@ pip install --upgrade pip setuptools
 pip install -r requirements.txt
 ```
 
+Install Flatten Tool:
+
+```bash
+pip install ./flatten-tool
+```
+
 ### Resolve check failures
 
 #### mdformat
@@ -202,6 +209,25 @@ To deploy the `dev` branch to the live documentation site, [create a pull reques
    ```
 1. Commit your changes.
 
+
+## Add an RDLS metadata example
+
+1. Author your example RDLS metadata in JSON format. You can use either a text editor or the [RDLS spreadsheet template](https://github.com/GFDRR/rdls-spreadsheet-template/) and [Flatten Tool](https://flatten-tool.readthedocs.io/en/latest/). Your example RDLS metadata must be wrapped in an outer `datasets` array, e.g.
+
+```json
+{
+  "datasets": [
+    {
+      "id": "1",
+      "title": "My example RDLS metadata"
+    }
+  ]
+}
+```
+1. Save your example JSON file to `examples/{component}/{title}/example.json` where `{component}` is the risk data component the example relates to (hazard, exposure, loss or vulnerability) and `{title}` is the title of the example.
+1. Run `./manage.py pre-commit` to create a CSV version of the example.
+1. Add Sphinx directives to the Markdown files in `docs` to render your example in the built documentation.
+
 ## Style guides
 
 ### Changelog style guide
@@ -258,7 +284,8 @@ Feature branches branch off the `dev` branch, with work merged into the `dev` br
   - `.tx/`: Transifex configuration (not yet implemented)
   - `img/`: Images used in the documentation
   - `locale/`: Translations of the English documentation (not yet implemented)
-- `schema/`: schema-related files
+- `examples`: Example JSON files, CSV files and figures
+- `schema/`: schema- and codelist-related files
 - `specs/`: TBD
 - `SteeringCommittee/`: Minutes of steering committee meetings
 

docs/_static/extra.css

@@ -71,4 +71,7 @@ margin-right: 20px;
 svg[id^="mermaid-"] {
   width: 100%;
   max-width: 80em;
-}
+}
+.wy-table-responsive table th {
+  white-space: pre;
+}

docs/_static/json-example-format.js

@@ -0,0 +1,36 @@
+   $( document ).ready(function() {
+         $(".expandjson").each(function(){
+          classList = $(this).attr("class").split(/\s+/);
+          expand = []
+          $.each(classList, function(index, item) {
+            if (item.indexOf('expand') === 0) {
+              expand.push(item.replace('expand-',''))
+            }
+            if (item.indexOf('file') === 0) {
+              filename = item
+            }
+          });
+          jsontext = $(this).text().trim()
+          json = JSON.parse(jsontext)
+          if(json.length) {
+              json = json[0]
+          }
+          $(this).html(renderjson.set_show_to_level(1).set_max_string_length(100).set_default_open(expand)(json))
+          if($(this).siblings(".selection-container").length === 0) { // NEED TO FIX THE CODE HERE. MOVE THINGS INTO THE PARENT CLASS CORRECTLY!
+              id = Math.floor(5 * (Math.random() % 1));
+              $(this).wrap("<div class='selection-container'></div>")
+              $(this).parent().prepend(
+                  $("<select name='select-"+id +"'></select>")
+                  .change(function(){ 
+                       $(this).siblings(".expandjson").hide();
+                       $(this).siblings("."+ $(this).val()).show();
+                   }))
+              $(this).siblings("select").append($("<option></option>").attr("value",filename).text(filename.replace("file-",""))) 
+          } else {   
+              container = $(this).siblings(".selection-container")
+              $(this).detach().appendTo(container)
+              $(this).siblings("select").append($("<option></option>").attr("value",filename).text(filename.replace("file-",""))) 
+              $(this).hide()
+          }
+       });
+   });

docs/_static/renderjson.css

@@ -0,0 +1,11 @@
+pre.renderjson { overflow: scroll; font-size:smaller; border: 1px solid #e1e4e5; padding: 12px; background-color: #eeffcc;}
+.renderjson a { text-decoration: none; }
+.renderjson .disclosure { color: grey; font-size: 150%; }
+.renderjson .syntax { color: grey; }
+.renderjson .string { color: #4070a0; }
+.renderjson .number { color: darkcyan; }
+.renderjson .boolean { color: blueviolet; }
+.renderjson .key    { color: #062873; font-weight: bold;}
+.renderjson .keyword { color: blue; }
+.renderjson .object.syntax { color: grey; }
+.renderjson .array.syntax  { color: grey; }

docs/_static/renderjson.js

@@ -0,0 +1,194 @@
+// Copyright © 2013-2014 David Caldwell <[email protected]>
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+// Usage
+// -----
+// The module exports one entry point, the `renderjson()` function. It takes in
+// the JSON you want to render as a single argument and returns an HTML
+// element.
+//
+// Options
+// -------
+// renderjson.set_icons("+", "-")
+//   This Allows you to override the disclosure icons.
+//
+// renderjson.set_show_to_level(level)
+//   Pass the number of levels to expand when rendering. The default is 0, which
+//   starts with everything collapsed. As a special case, if level is the string
+//   "all" then it will start with everything expanded.
+//
+// renderjson.set_max_string_length(length)
+//   Strings will be truncated and made expandable if they are longer than
+//   `length`. As a special case, if `length` is the string "none" then
+//   there will be no truncation. The default is "none".
+//
+// renderjson.set_sort_objects(sort_bool)
+//   Sort objects by key (default: false)
+//
+// Theming
+// -------
+// The HTML output uses a number of classes so that you can theme it the way
+// you'd like:
+//     .disclosure    ("⊕", "⊖")
+//     .syntax        (",", ":", "{", "}", "[", "]")
+//     .string        (includes quotes)
+//     .number
+//     .boolean
+//     .key           (object key)
+//     .keyword       ("null", "undefined")
+//     .object.syntax ("{", "}")
+//     .array.syntax  ("[", "]")
+
+var module;
+(module||{}).exports = renderjson = (function() {
+    var themetext = function(/* [class, text]+ */) {
+        var spans = [];
+        while (arguments.length)
+            spans.push(append(span(Array.prototype.shift.call(arguments)),
+                              text(Array.prototype.shift.call(arguments))));
+        return spans;
+    };
+    var append = function(/* el, ... */) {
+        var el = Array.prototype.shift.call(arguments);
+        for (var a=0; a<arguments.length; a++)
+            if (arguments[a].constructor == Array)
+                append.apply(this, [el].concat(arguments[a]));
+            else
+                el.appendChild(arguments[a]);
+        return el;
+    };
+    var prepend = function(el, child) {
+        el.insertBefore(child, el.firstChild);
+        return el;
+    }
+    var isempty = function(obj) { for (var k in obj) if (obj.hasOwnProperty(k)) return false;
+                                  return true; }
+    var text = function(txt) { return document.createTextNode(txt) };
+    var div = function() { return document.createElement("div") };
+    var span = function(classname) { var s = document.createElement("span");
+                                     if (classname) s.className = classname;
+                                     return s; };
+    var A = function A(txt, classname, callback) { var a = document.createElement("a");
+                                                   if (classname) a.className = classname;
+                                                   a.appendChild(text(txt));
+                                                   a.href = '#';
+                                                   a.onclick = function() { callback(); return false; };
+                                                   return a; };
+
+    function _renderjson(json, indent, dont_indent, show_level, max_string, sort_objects) {
+        var my_indent = dont_indent ? "" : indent;
+        var disclosure = function(open, placeholder, close, type, builder) {
+            var content;
+            var empty = span(type);
+            var show = function() { if (!content) append(empty.parentNode,
+                                                         content = prepend(builder(),
+                                                                           A(renderjson.hide, "disclosure",
+                                                                             function() { content.style.display="none";
+                                                                                          empty.style.display="inline"; } )));
+                                    content.style.display="inline";
+                                    empty.style.display="none"; };
+            append(empty,
+                   A(renderjson.show, "disclosure", show),
+                   themetext(type+ " syntax", open),
+                   A(placeholder, null, show),
+                   themetext(type+ " syntax", close));
+
+            var el = append(span(), text(my_indent.slice(0,-1)), empty);
+            if (show_level > 0)
+                show();
+            return el;
+
+        };
+
+        if (json === null) return themetext(null, my_indent, "keyword", "null");
+        if (json === void 0) return themetext(null, my_indent, "keyword", "undefined");
+
+        if (typeof(json) == "string" && json.length > max_string)
+            return disclosure('"', json.substr(0,max_string)+" ...", '"', "string", function () {
+                return append(span("string"), themetext(null, my_indent, "string", JSON.stringify(json)));
+            });
+
+        if (typeof(json) != "object") // Strings, numbers and bools
+            return themetext(null, my_indent, typeof(json), JSON.stringify(json));
+
+        if (json.constructor == Array) {
+            if (json.length == 0) return themetext(null, my_indent, "array syntax", "[]");
+
+            return disclosure("[", " ... ", "]", "array", function () {
+                var as = append(span("array"), themetext("array syntax", "[", null, "\n"));
+                for (var i=0; i<json.length; i++)
+                    append(as,
+                           _renderjson(json[i], indent+"    ", false, show_level-1, max_string, sort_objects),
+                           i != json.length-1 ? themetext("syntax", ",") : [],
+                           text("\n"));
+                append(as, themetext(null, indent, "array syntax", "]"));
+                return as;
+            });
+        }
+
+        // object
+        if (isempty(json))
+            return themetext(null, my_indent, "object syntax", "{}");
+
+        return disclosure("{", "...", "}", "object", function () {
+            var os = append(span("object"), themetext("object syntax", "{", null, "\n"));
+            for (var k in json) var last = k;
+            var keys = Object.keys(json);
+            if (sort_objects)
+                keys = keys.sort();
+            for (var i in keys) {
+                var k = keys[i];
+                append(os, themetext(null, indent+"    ", "key", '"'+k+'"', "object syntax", ': '),
+                       _renderjson(json[k], indent+"    ", true, ((renderjson.default_open.indexOf(k) > -1) ? show_level + 1 : show_level - 1 ), max_string, sort_objects),
+                       k != last ? themetext("syntax", ",") : [],
+                       text("\n"));
+            }
+            append(os, themetext(null, indent, "object syntax", "}"));
+            return os;
+        });
+    }
+
+    var renderjson = function renderjson(json)
+    {
+        var pre = append(document.createElement("pre"), _renderjson(json, "", false, renderjson.show_to_level, renderjson.max_string_length, renderjson.sort_objects));
+        pre.className = "renderjson";
+        return pre;
+    }
+    renderjson.set_icons = function(show, hide) { renderjson.show = show;
+                                                  renderjson.hide = hide;
+                                                  return renderjson; };
+    renderjson.set_show_to_level = function(level) { renderjson.show_to_level = typeof level == "string" &&
+                                                                                level.toLowerCase() === "all" ? Number.MAX_VALUE
+                                                                                                              : level;
+                                                     return renderjson; };
+    renderjson.set_max_string_length = function(length) { renderjson.max_string_length = typeof length == "string" &&
+                                                                                         length.toLowerCase() === "none" ? Number.MAX_VALUE
+                                                                                                                         : length;
+                                                          return renderjson; };
+    renderjson.set_sort_objects = function(sort_bool) { renderjson.sort_objects = sort_bool;
+                                                        return renderjson; };
+    // Backwards compatiblity. Use set_show_to_level() for new code.
+    renderjson.set_show_by_default = function(show) { renderjson.show_to_level = show ? Number.MAX_VALUE : 0;
+                                                      return renderjson; };
+
+    //Added by timgdavies
+    renderjson.set_default_open = function(node_list) { renderjson.default_open = node_list ? node_list : [] ; return renderjson; };
+
+    renderjson.set_icons('⊕', '⊖');
+    renderjson.set_show_by_default(false);
+    renderjson.set_sort_objects(false);
+    renderjson.set_max_string_length("none");
+    renderjson.set_default_open([]);
+    return renderjson;
+})();

docs/_templates/layout.html

@@ -1,4 +1,4 @@
 {% extends "!layout.html" %}
 
-{% set css_files = css_files + ["_static/basic.css"] %}
-
+{% set css_files = css_files + ["_static/renderjson.css", "_static/jsonschema.css"] %}
+{% set script_files = script_files + ["_static/renderjson.js", "_static/json-example-format.js"] %}

docs/about/changelog.md

@@ -102,6 +102,7 @@ This page lists changes to the Risk Data Library Standard.
 - [#146](https://github.com/GFDRR/rdl-standard/pull/146) - Update introduction to the RDLS reference section.
 - [#193](https://github.com/GFDRR/rdl-standard/pull/193) - Fix lists of referencing fields for subschemas and codelists.
 - [#225](https://github.com/GFDRR/rdl-standard/pull/225) - Update high level descriptions of the 4 risk data components.
+- [#196](https://github.com/GFDRR/rdl-standard/pull/196) - Add examples to schema reference documentation.
 
 ### Non-normative documentation