[nfc] Add ability to test code snippets

This demonstrates a flow that can be used to validate that all code
snippets used in the FIRRTL specification correctly parse.  This is
implemented using a simple pandoc filter to extract the bodies of all code
blocks with known languages (FIRRTL and Verilog), write them to the build
directory, and then run them all through an appropriate tool based on file
extension (firtool or verilator).  This may be a little cumbersome as
every code example has to be completely legal.  I.e., this would require a
version and circuit on every FIRRTL code example.  This may, however, not
be such a bad thing.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

Makefile

@@ -5,7 +5,7 @@ IMG_SRCS=$(shell find include/img_src/ -type f -name '*.dot')
 IMG_EPSS=$(IMG_SRCS:include/img_src/%.dot=build/%.eps)
 IMG_PNG=$(IMG_SRCS:include/img_src/%.dot=build/%.png)
 
-.PHONY: all clean format images
+.PHONY: all clean format images test
 .PRECIOUS: build/ build/img/
 
 all: build/spec.pdf build/abi.pdf
@@ -18,6 +18,12 @@ format:
 
 images: $(IMG_EPSS) $(IMG_PNGS)
 
+test: abi.md spec.md | build/
+	pandoc --filter scripts/extract-firrtl-code.py $^ -o /dev/null
+	find -s build/ -type f -name '*.fir' | xargs -n1 firtool -parse-only -o /dev/null
+	find -s build/ -type f -name '*.v' | xargs -n1 verilator --default-language 1364-2005 -Wall -Wno-DECLFILENAME --lint-only -o /dev/null
+	find -s build/ -type f -name '*.sv' | xargs -n1 verilator --default-language 1800-2017 -Wall -Wno-DECLFILENAME --lint-only -o /dev/null
+
 PANDOC_FLAGS=\
 	--pdf-engine=latexmk \
 	--pdf-engine-opt=-logfilewarninglist \

scripts/extract-firrtl-code.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+
+from pandocfilters import toJSONFilter, CodeBlock
+
+index = 0
+classToExtension = {
+    'firrtl': 'fir',
+    'verilog': 'v',
+    'systemverilog': 'sv'
+}
+
+def extractFIRRTLCode(key, value, format, meta):
+    global index
+    if not key == 'CodeBlock':
+        return
+
+    [[ident, classes, keyvals], code] = value
+
+    extension = None
+    for c, e in classToExtension.items():
+        if c in classes:
+            extension = e
+
+    if not extension:
+        return
+
+    with open(f'build/code-example-{index:03d}.{extension}', 'w') as f:
+        f.write(code)
+        f.write('\n')
+
+    index += 1
+
+if __name__ == "__main__":
+    toJSONFilter(extractFIRRTLCode)