[Docs] Make build actually strict

[antonymilne]

Description

We run mkdocs build with --strict in order to catch errors like broken links, but this isn't doing anything because by default the messages are raised with level iNFO and not the required WARNING that would then be elevated to ERROR by --strict. See https://www.mkdocs.org/user-guide/configuration/#validation for explanation of these options.

mkdocs serve is just for development purposes so shouldn't fail with warnings, hence I removed --strict there.

Linkchecker still works as before, which is an external tool outside mkdocs and checks the built documentation by following external links. Since we now ignore links to our RTD docs themselves (see #524) it is essential we make our checks stricter so that we don't miss broken internal links within our own docs.

Changes to fix warnings include:

• Fix broken anchor links (due to renaming)
• Fix missing .md extension

Notice

• I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[maxschulz-COL]

lgtm!

[huong-li-nguyen]

I just looked at the new warnings. It shouldn't be too strict, and we should fix them. They also made it clear that there are a couple of broken links because of renamings of titles 😅

Maybe @stichbury can help you with this?

[stichbury]

I just looked at the new warnings. It shouldn't be too strict, and we should fix them. They also made it clear that there are a couple of broken links because of renamings of titles 😅

Maybe @stichbury can help you with this?

Sure, happy to fix these in the next sprint, just stick me on the ticket and I'll pick it up w/c 24th June.

[huong-li-nguyen]

Sure, happy to fix these in the next sprint, just stick me on the ticket and I'll pick it up w/c 24th June.

@stichbury - I hope you don't mind I took this over! I actually just wanted to check in this PR whether I've introduced any new broken anchor links with the recent PRs I've just merged. And it turned out that I did add some broken anchor links again 😅 It's very good that we have the strict check in place now!

When I started to fix them, I just fixed all of them 😄 We also plan to do the release on Monday, so probably better to have the docs fixed until then 👍

Feel free to review the changes though 🙏

[stichbury]

@stichbury - I hope you don't mind I took this over!

Of course not, and thank you 🌟 that's a big help and timesaver for me.

[stichbury]

Looks great. Always good to be strict 🎓