Sort out docs errors

[josephjclark]

When the docs build runs, it'll report a bunch of errors and warnings.

These are ignored by the CI build - but probably it's about time we forced the build to fail and make us get on and fix the problems.

We can only do this when we've validated that any errors currently being thrown are valid - I think there's a lot of out of date stuff in the validator which need addressing.

We also need to add a warning for embedding an {@link} tag in an example caption, which causes problems (in the doc site and lightning). See #856

See also #684 #525

I think we should also absorb simple-ast as part of this work, see #13