Fix broken links in docs and fail CI unless docs build cleanly

[michaelkirk]

• [x] I agree to follow the project's code of conduct.

• [-] I added an entry to CHANGES.md if knowledge of this change could be valuable to users.

Two changes:

The first fails CI unless docs build cleanly. This should help us avoid broken links etc. in our docs.

The second commit (forthcoming) fixes the CI failure. I pushed up the first commit separately so you can see what it looks like when CI fails for this reason.

[michaelkirk]

Ok! You can check the first commit's status to see what a failed docs build looks like, and then you can see it resolved in the second commit's build.

[urschrei]

This is wonderful