Description

Allow diagrams using mermaid.js

Context

Some things need a diagram to best explain them, mermaid syntax will work well with
markdown docs and the be easier to maintain than exporting images.

Possible implementation

look at existing mermaid extensions for sphinx, ideally it will work with GitHub's rendering of mermaid diagrams.