Idea: Convert to RST/Sphinx and use doctest.

[pipermerriam]

I was perusing the spec and see there are a lot of code blocks with example code.

If this spec were to be converted to RST/Sphinx then you could benefit from using doctest allowing you to verify that your example implementations pass some set of test vectors, etc.

For Reference: http://www.sphinx-doc.org/en/stable/ext/doctest.html

We use doctest in most of our python repositories and it is the single most important thing that ensures our documentation is up-to-date and doesn't diverge from the code itself.

[ralexstokes]

i will +1 this idea, with the caveat that we should probably wait for some kind of spec release candidate i have heard rumors about...

but the closer the spec is to executable the better -- this would also motivate us to actually write and maintain spec test vectors which are helpful to implementers and anyone else aiming to understand the spec (just like unit tests in your codebase).

and while we are on the topic, it's worth noting that the logical extreme of this is just turning the spec into literate K (or Coq or whatever) so that any tests we write turn into formal specifications

[JustinDrake]

Executable or semi-executable specs are a good idea. I'm slowly working towards one in Go, Vitalik may be working on one in Python, and RuntimeVerification may write one in K.

Anyone who wants to take this on please reopen :)

[JustinDrake]

I think this can be closed given #835 is closed. Feel free to reopen :)