[nfc] Add ability to test code snippets

[seldridge]

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. To alleviate this, this PR includes the ability to add special
delimiters, indicated by lines with the text snippetbegin/snippetend which
will cause the filter to extract only the lines between the delimiters.

CC: @dtzSiFive

[seldridge]

This now includes basic delimited support. The magic delimiters snippetbegin/snippetend can be used to extract out any number of code regions. E.g., this allows you to do things like:

FIRRTL version 4.0.0
circuit Foo:
  module Foo:
    input a: UInt<1>
    output b: UInt<1>

    ;; snippetbegin
    connect b, a
    ;; snippetend

This will extract the entire code block to a file. It will replace the original code block with:

    connect b, a

[mmaloney-sf]

Just to be sure, the line comment syntax is ; ... in FIRRTL and not // ... right? (Your example in the PR looks like it will error out. I don't know if that's material to the logic, though).

[mwachs5]

could we add a few sentences to CONTRIBUTING.md that explains this a little bit?

[seldridge]

Just to be sure, the line comment syntax is ; ... in FIRRTL and not // ... right? (Your example in the PR looks like it will error out. I don't know if that's material to the logic, though).

Yes! That's a mistake. The filter will still handle that, but that is illegal FIRRTL. The intent is that the code should put the snippetbegin/snippetend delimiters inside a comment.

[seldridge]

This is good for a final review. I will open a second PR which fixes all the code examples. We can then turn this on in CI.

[seldridge]

This newline helps for readability and avoids a Verilator lint warning that we don't have to waive.

[seldridge]

This allows opting out from testing for a specific snippet using syntax like {.firrtl .notest} on the code block. This is very helpful for things that are really annoying to test like Verilog that includes input files or FIRRTL code blocks that are intentionally not legal through the use of pseudo-type parameters (see memories).

[seldridge]

@mwachs5 wrote:

could we add a few sentences to CONTRIBUTING.md that explains this a little bit?

Added in the force push!

[mikeurbach]

This is my first exposure to pandoc filters, so I don't have any strong comments on the lua implementation. The usage and goal makes sense to me in general.