Switch to JSON5 to improve usability.

The `json5` library self-describes as extremely slow, but this is not
a concern for our use case.

This enables many improvements, including but not limited to:
- trailing commas,
- ECMAScript identifiers as object keys,
- hexadecimal numbers,
- comments,
- and more described at https://json5.org/.

README.md

@@ -3,7 +3,7 @@ sphinxcontrib-yowasp-wavedrom
 
 This [Sphinx] extension allows embedding [WaveDrom] waveform, bitfield, and circuit diagrams into Sphinx documents.
 
-This extension uses the [YoWASP WaveDrom][yowasp-wavedrom] package to ensure that diagrams are rendered exactly the same as in the WaveDrom editor, without having to follow a decision tree for configuration, without requiring any additional tools to be installed on the system used to build documentation, without requiring any native dependencies to be installed on that system, without requiring JavaScript for browsing documentation, and without slowing down the Sphinx build process. It also reports syntax and semantic errors with accurate source locations. <!-- environmental storytelling paragraph --> 
+This extension uses the [YoWASP WaveDrom][yowasp-wavedrom] package to ensure that diagrams are rendered exactly the same as in the WaveDrom editor, without having to follow a decision tree for configuration, without requiring any additional tools to be installed on the system used to build documentation, without requiring any native dependencies to be installed on that system, without requiring JavaScript for browsing documentation, and without slowing down the Sphinx build process. It also reports syntax and semantic errors with accurate source locations. <!-- environmental storytelling paragraph -->
 
 WaveJSON diagram descriptions are always converted into SVG files; only the HTML builder is supported at the moment. **Make sure to follow the instructions in the [color schemes] section!**
 
@@ -20,13 +20,25 @@ This extension provides only one directive, `wavedrom`. Its argument is the base
 
 ```rst
 .. wavedrom:: clk_and_data
-    
-    {"signal": [  
+
+    {"signal": [
         {"name": "clk",  "wave": "n..."},
         {"name": "data", "wave": "01.0"}
     ]}
 ```
 
+This extension also accepts WaveJSON files in the more human-friendly [JSON5](https://json5.org) format:
+
+```rst
+.. wavedrom:: clk_and_data
+
+    {signal: [
+        {name: 'clk',  wave: 'n...'},
+        // a single pulse
+        {name: 'data', wave: '01.0'},
+    ]}
+```
+
 Additional examples are available [in the test suite](/test/index.rst), as well as the corresponding [rendered output](https://yowasp.github.io/sphinxcontrib-wavedrom/).
 
 

pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
     "importlib_resources; python_version<'3.9'",
     "Sphinx~=7.1",
     "yowasp-wavedrom>=3.5.0.8",
+    "json5~=0.9", # trailing commas
 ]
 
 [build-system]

sphinxcontrib/yowasp_wavedrom.py

@@ -1,5 +1,5 @@
 import re
-import json
+import json5 as json
 from pathlib import Path
 from docutils.parsers.rst import Directive
 from docutils import nodes
@@ -69,7 +69,7 @@ def html_visit_wavedrom_diagram(self: sphinx.writers.html5.HTML5Translator, node
         css_class = "wavedrom wavedrom-reg"
     if "assign" in wavedrom_src:
         css_class = "wavedrom wavedrom-assign"
-    
+
     # Write the SVG to output directory. This is necessary because inlining it into the HTML has
     # significantly different behavior: duplicate IDs result in broken rendering, text can be
     # selected, media queries can't be overridden with a `color-scheme` CSS attribute for themes

test/index.rst

@@ -8,34 +8,41 @@ Waveform diagrams
 default:
 
 .. wavedrom:: skin_default
-    
-    {"signal": [  
+
+    {"signal": [
         {"name": "clk",  "wave": "n..."},
         {"name": "data", "wave": "01.0"}
     ]}
 
+.. test trailing commas
+
 light:
 
 .. wavedrom:: skin_light
-    
+
     {
-        "signal": [  
+        "signal": [
             {"name": "clk",  "wave": "p..."},
-            {"name": "data", "wave": "01.0"}
+            {"name": "data", "wave": "01.0"},
         ],
-        "config": {"skin": "light"}
+        "config": {"skin": "light"},
     }
 
+.. test ECMAScript object keys
+.. test single quoted strings
+.. test comments
+
 dark:
 
 .. wavedrom:: skin_dark
-    
+
     {
-        "signal": [  
-            {"name": "clk",  "wave": "p..."},
-            {"name": "data", "wave": "01.0"}
+        signal: [
+            {name: 'clk',  wave: 'p...'},
+            // one pulse
+            {name: 'data', wave: '01.0'}
         ],
-        "config": {"skin": "dark"}
+        config: {skin: 'dark'}
     }
 
 narrow:
@@ -44,9 +51,9 @@ narrow:
     test nested base names
 
 .. wavedrom:: extra/skin_narrow
-    
+
     {
-        "signal": [  
+        "signal": [
             {"name": "clk",  "wave": "n..."},
             {"name": "data", "wave": "01.0"}
         ],
@@ -76,9 +83,9 @@ Circuit diagrams
 
     {
         "assign": [
-            ["out", 
-                ["|", 
-                    ["&", ["~", "a"], "b"], 
+            ["out",
+                ["|",
+                    ["&", ["~", "a"], "b"],
                     ["&", ["~", "b"], "a"]
                 ]
             ]