Make dead links stand out

[random-person-001]

It'd be cool if we could more easily see which links go to unwritten pages when browsing around. Wikipedia's redlinks come to mind. Anyone know of a tool or something that will help with this automatically?

[peytondmurray]

So there's a few parts to this:

1. Let's turn on nitpicky mode to make all broken refs throw warnings
2. Make sphinx turn warnings into errors to prevent broken refs from entering the build at all
3. Let's set up a CI job to automatically test links. We can do this by running sphinx-build -b linkcheck

[random-person-001]

If possible, I think it'd be cool to still have the broken refs make it into the final doc build, but just be visually distinct from working ones while there

[peytondmurray]

Hmm, why do we want broken links to appear in the build?

[random-person-001]

I was thinking it could help with showing users "hey we could use some more content here" in mid to late stages of the wiki in a nice manner.

But the bigger reason I see is once the article gets written, I think it'd be a lot easier to link previous articles to it. I don't like the idea of trawling through all of the current wiki even with regex or something to find words in other pages that should be linkified. Rather, if the links are already there, we can just tell the software to list dead links and more easily update the ones that should be to the newly written page.

[random-person-001]

Now that we have a ton of stubs, I'm cool with changing our build workflow to not allow broken refs

So there's a few parts to this:

1. Let's turn on [nitpicky mode](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky) to make all broken refs throw warnings

2. Make sphinx [turn warnings into errors](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-W) to prevent broken refs from entering the build at all

3. Let's set up a CI job to automatically test links. We can do this by running `sphinx-build -b linkcheck`

[peytondmurray]

I'm happy to do this then!