Skip to content

Commit

Permalink
Merge pull request #196 from GFDRR/135-examples
Browse files Browse the repository at this point in the history
135 examples
  • Loading branch information
duncandewhurst authored Aug 30, 2023
2 parents 0a3eafe + 4e03e34 commit 2cb3558
Show file tree
Hide file tree
Showing 68 changed files with 2,815 additions and 157 deletions.
4 changes: 4 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -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
31 changes: 29 additions & 2 deletions developer_docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
5 changes: 4 additions & 1 deletion docs/_static/extra.css
Original file line number Diff line number Diff line change
Expand Up @@ -71,4 +71,7 @@ margin-right: 20px;
svg[id^="mermaid-"] {
width: 100%;
max-width: 80em;
}
}
.wy-table-responsive table th {
white-space: pre;
}
36 changes: 36 additions & 0 deletions docs/_static/json-example-format.js
Original file line number Diff line number Diff line change
@@ -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()
}
});
});
11 changes: 11 additions & 0 deletions docs/_static/renderjson.css
Original file line number Diff line number Diff line change
@@ -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; }
194 changes: 194 additions & 0 deletions docs/_static/renderjson.js
Original file line number Diff line number Diff line change
@@ -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;
})();
4 changes: 2 additions & 2 deletions docs/_templates/layout.html
Original file line number Diff line number Diff line change
@@ -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"] %}
1 change: 1 addition & 0 deletions docs/about/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading

0 comments on commit 2cb3558

Please sign in to comment.