Added JSON viewer to docs

docs/examples/saving_and_loading.py → docs/examples/1_saving_and_loading.py

@@ -11,20 +11,36 @@
 
 """
 
+import json
+
+
+class JSON:
+    def __init__(self, data):
+        if isinstance(data, dict):
+            json_str = json.dumps(data)
+        else:
+            json_str = data
+
+        self.json_str = json_str
+
+    def _repr_html_(self):
+        return (
+            f'<pre class="json">{self.json_str}</pre>'
+        )
+
 # %%
 # ## Loading Datasets
 # Suppose we have an example dataset stored in the **AOEF** format. The dataset
 # is stored as a text file following the JSON structure. To view the contents
 # of the file, you can use the following code.
 
-import json
 from pathlib import Path
 
 dataset_path = Path("example_dataset.json")
 with open(dataset_path) as file:
     dataset_contents = json.load(file)
 
-print(json.dumps(dataset_contents, indent=4))
+JSON(dataset_contents)
 
 # %%
 # However, using the loading functions provided by the `soundevent` package,

docs/examples/my_dataset.json

@@ -1 +1 @@
-{"info":{"id":"c1cb90ed-5486-4996-a7dd-b2d4a5de8251","name":"test_dataset","description":"A test dataset.","date_created":"2023-07-14T21:49:35.173942"},"tags":[{"id":0,"key":"species","value":"Myotis myotis"},{"id":1,"key":"sex","value":"female"},{"id":2,"key":"behaviour","value":"foraging"},{"id":3,"key":"species","value":"Eptesicus serotinus"},{"id":4,"key":"sex","value":"male"},{"id":5,"key":"behaviour","value":"social calls"}],"recordings":[{"id":"c6e43cbb-1a55-467c-9071-0774b0198969","path":"recording1.wav","duration":10.0,"channels":1,"samplerate":441000,"time_expansion":10.0,"hash":"1234567890abcdef","date":"2021-01-01","time":"21:34:56","latitude":12.345,"longitude":34.567,"tags":[0,1,2],"features":{"SNR":10.0,"ACI":0.5},"notes":[{"uuid":"8ed5b892-86cf-4f39-bb3a-c97b9f5c0f6b","message":"This is a note.","created_by":"John Doe","is_issue":false,"created_at":"2021-01-01T12:34:56"}]},{"id":"43cbf2e1-87ae-4ff8-af9e-7038e0300e39","path":"recording2.wav","duration":8.0,"channels":1,"samplerate":441000,"time_expansion":10.0,"hash":"234567890abcdef1","date":"2021-01-02","time":"19:34:56","latitude":13.345,"longitude":32.567,"tags":[3,4,5],"features":{"SNR":7.0,"ACI":0.3},"notes":[{"uuid":"429c455c-eb45-4f5e-99e6-35d06119463e","message":"Unsure about the species.","created_by":"John Doe","is_issue":false,"created_at":"2021-01-01T12:34:56"}]}]}
+{"info":{"uuid":"c1cb90ed-5486-4996-a7dd-b2d4a5de8251","name":"test_dataset","description":"A test dataset.","date_created":"2023-07-15T21:48:34.658222"},"tags":[{"id":0,"key":"species","value":"Myotis myotis"},{"id":1,"key":"sex","value":"female"},{"id":2,"key":"behaviour","value":"foraging"},{"id":3,"key":"species","value":"Eptesicus serotinus"},{"id":4,"key":"sex","value":"male"},{"id":5,"key":"behaviour","value":"social calls"}],"recordings":[{"id":0,"uuid":"c6e43cbb-1a55-467c-9071-0774b0198969","path":"recording1.wav","duration":10.0,"channels":1,"samplerate":441000,"time_expansion":10.0,"hash":"1234567890abcdef","date":"2021-01-01","time":"21:34:56","latitude":12.345,"longitude":34.567,"tags":[0,1,2],"features":{"SNR":10.0,"ACI":0.5},"notes":[{"uuid":"8ed5b892-86cf-4f39-bb3a-c97b9f5c0f6b","message":"This is a note.","created_by":"John Doe","is_issue":false,"created_at":"2021-01-01T12:34:56"}]},{"id":1,"uuid":"43cbf2e1-87ae-4ff8-af9e-7038e0300e39","path":"recording2.wav","duration":8.0,"channels":1,"samplerate":441000,"time_expansion":10.0,"hash":"234567890abcdef1","date":"2021-01-02","time":"19:34:56","latitude":13.345,"longitude":32.567,"tags":[3,4,5],"features":{"SNR":7.0,"ACI":0.3},"notes":[{"uuid":"429c455c-eb45-4f5e-99e6-35d06119463e","message":"Unsure about the species.","created_by":"John Doe","is_issue":false,"created_at":"2021-01-01T12:34:56"}]}]}

docs/javascripts/jquery.json-viewer.js

@@ -0,0 +1,183 @@
+/**
+ * jQuery json-viewer
+ * @author: Alexandre Bodelot <alexandre.bodelot@gmail.com>
+ * @link: https://github.com/abodelot/jquery.json-viewer
+ */
+(function($) {
+
+  /**
+   * Check if arg is either an array with at least 1 element, or a dict with at least 1 key
+   * @return boolean
+   */
+  function isCollapsable(arg) {
+    return arg instanceof Object && Object.keys(arg).length > 0;
+  }
+
+  /**
+   * Check if a string looks like a URL, based on protocol
+   * This doesn't attempt to validate URLs, there's no use and syntax can be too complex
+   * @return boolean
+   */
+  function isUrl(string) {
+    var protocols = ['http', 'https', 'ftp', 'ftps'];
+    for (var i = 0; i < protocols.length; ++i) {
+      if (string.startsWith(protocols[i] + '://')) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Return the input string html escaped
+   * @return string
+   */
+  function htmlEscape(s) {
+    return s.replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/'/g, '&apos;')
+      .replace(/"/g, '&quot;');
+  }
+
+  /**
+   * Transform a json object into html representation
+   * @return string
+   */
+  function json2html(json, options) {
+    var html = '';
+    if (typeof json === 'string') {
+      // Escape tags and quotes
+      json = htmlEscape(json);
+
+      if (options.withLinks && isUrl(json)) {
+        html += '<a href="' + json + '" class="json-string" target="_blank">' + json + '</a>';
+      } else {
+        // Escape double quotes in the rendered non-URL string.
+        json = json.replace(/&quot;/g, '\\&quot;');
+        html += '<span class="json-string">"' + json + '"</span>';
+      }
+    } else if (typeof json === 'number' || typeof json === 'bigint') {
+      html += '<span class="json-literal">' + json + '</span>';
+    } else if (typeof json === 'boolean') {
+      html += '<span class="json-literal">' + json + '</span>';
+    } else if (json === null) {
+      html += '<span class="json-literal">null</span>';
+    } else if (json instanceof Array) {
+      if (json.length > 0) {
+        html += '[<ol class="json-array">';
+        for (var i = 0; i < json.length; ++i) {
+          html += '<li>';
+          // Add toggle button if item is collapsable
+          if (isCollapsable(json[i])) {
+            html += '<a href class="json-toggle"></a>';
+          }
+          html += json2html(json[i], options);
+          // Add comma if item is not last
+          if (i < json.length - 1) {
+            html += ',';
+          }
+          html += '</li>';
+        }
+        html += '</ol>]';
+      } else {
+        html += '[]';
+      }
+    } else if (typeof json === 'object') {
+      // Optional support different libraries for big numbers
+      // json.isLosslessNumber: package lossless-json
+      // json.toExponential(): packages bignumber.js, big.js, decimal.js, decimal.js-light, others?
+      if (options.bigNumbers && (typeof json.toExponential === 'function' || json.isLosslessNumber)) {
+        html += '<span class="json-literal">' + json.toString() + '</span>';
+      } else {
+        var keyCount = Object.keys(json).length;
+        if (keyCount > 0) {
+          html += '{<ul class="json-dict">';
+          for (var key in json) {
+            if (Object.prototype.hasOwnProperty.call(json, key)) {
+              // define a parameter of the json value first to prevent get null from key when the key changed by the function `htmlEscape(key)`
+              let jsonElement = json[key];
+              key = htmlEscape(key);
+              var keyRepr = options.withQuotes ?
+                '<span class="json-string">"' + key + '"</span>' : key;
+
+              html += '<li>';
+              // Add toggle button if item is collapsable
+              if (isCollapsable(jsonElement)) {
+                html += '<a href class="json-toggle">' + keyRepr + '</a>';
+              } else {
+                html += keyRepr;
+              }
+              html += ': ' + json2html(jsonElement, options);
+              // Add comma if item is not last
+              if (--keyCount > 0) {
+                html += ',';
+              }
+              html += '</li>';
+            }
+          }
+          html += '</ul>}';
+        } else {
+          html += '{}';
+        }
+      }
+    }
+    return html;
+  }
+
+  /**
+   * jQuery plugin method
+   * @param json: a javascript object
+   * @param options: an optional options hash
+   */
+  $.fn.jsonViewer = function(json, options) {
+    // Merge user options with default options
+    options = Object.assign({}, {
+      collapsed: false,
+      rootCollapsable: true,
+      withQuotes: false,
+      withLinks: true,
+      bigNumbers: false
+    }, options);
+
+    // jQuery chaining
+    return this.each(function() {
+
+      // Transform to HTML
+      var html = json2html(json, options);
+      if (options.rootCollapsable && isCollapsable(json)) {
+        html = '<a href class="json-toggle"></a>' + html;
+      }
+
+      // Insert HTML in target DOM element
+      $(this).html(html);
+      $(this).addClass('json-document');
+
+      // Bind click on toggle buttons
+      $(this).off('click');
+      $(this).on('click', 'a.json-toggle', function() {
+        var target = $(this).toggleClass('collapsed').siblings('ul.json-dict, ol.json-array');
+        target.toggle();
+        if (target.is(':visible')) {
+          target.siblings('.json-placeholder').remove();
+        } else {
+          var count = target.children('li').length;
+          var placeholder = count + (count > 1 ? ' items' : ' item');
+          target.after('<a href class="json-placeholder">' + placeholder + '</a>');
+        }
+        return false;
+      });
+
+      // Simulate click on toggle button when placeholder is clicked
+      $(this).on('click', 'a.json-placeholder', function() {
+        $(this).siblings('a.json-toggle').click();
+        return false;
+      });
+
+      if (options.collapsed == true) {
+        // Trigger click to collapse all nodes
+        $(this).find('a.json-toggle').click();
+      }
+    });
+  };
+})(jQuery);

docs/javascripts/json-viewer.js

@@ -0,0 +1,9 @@
+$("pre.json").each(function (i, obj) {
+  var json_str = $(obj).html();
+  var json_obj = JSON.parse(json_str);
+  $(obj).jsonViewer(json_obj, {
+    collapsed: true,
+    rootCollapsable: false,
+    withQuotes: true,
+  });
+});

docs/stylesheets/jquery.json-viewer.css

@@ -0,0 +1,57 @@
+/* Root element */
+.json-document {
+  padding: 1em 2em;
+}
+
+/* Syntax highlighting for JSON objects */
+ul.json-dict, ol.json-array {
+  list-style-type: none;
+  margin: 0 0 0 1px;
+  border-left: 1px dotted #ccc;
+  padding-left: 2em;
+}
+.json-string {
+  color: #0B7500;
+}
+.json-literal {
+  color: #1A01CC;
+  font-weight: bold;
+}
+
+/* Toggle button */
+a.json-toggle {
+  position: relative;
+  color: inherit;
+  text-decoration: none;
+}
+a.json-toggle:focus {
+  outline: none;
+}
+a.json-toggle:before {
+  font-size: 1.1em;
+  color: #c0c0c0;
+  content: "\25BC"; /* down arrow */
+  position: absolute;
+  display: inline-block;
+  width: 1em;
+  text-align: center;
+  line-height: 1em;
+  left: -1.2em;
+}
+a.json-toggle:hover:before {
+  color: #aaa;
+}
+a.json-toggle.collapsed:before {
+  /* Use rotated down arrow, prevents right arrow appearing smaller than down arrow in some browsers */
+  transform: rotate(-90deg);
+}
+
+/* Collapsable placeholder links */
+a.json-placeholder {
+  color: #aaa;
+  padding: 0 1em;
+  text-decoration: none;
+}
+a.json-placeholder:hover {
+  text-decoration: underline;
+}

mkdocs.yml

@@ -77,3 +77,11 @@ markdown_extensions:
       toc_depth: 4
       permalink: "#"
       separator: "_"
+
+extra_javascript:
+  - javascripts/jquery-3.3.1.min.js
+  - javascripts/jquery.json-viewer.js
+  - javascripts/json-viewer.js
+
+extra_css:
+  - stylesheets/jquery.json-viewer.css