1780411 - Automatically detect broken links when building docs in CI

Status: NEW

(Developer Infrastructure :: Source Documentation, enhancement)

Description

[Andrew Halberstadt [:ahal]]

It looks like Sphinx has a builder which can detect broken links and emit warnings:
https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder

We should either make this the default builder when building the main docs, or else stand up a linter that does this independently. I'd vote for the former, though the problem there is that we emit so many warnings that they would be easy to lose (IMO the solution here is to fix them all and get to a point where we have a green build).

Comment 1

[Andrew Halberstadt [:ahal]]

Thinking about it, a linter might be nice because then reviewbot could flag new instances of it even if we have tons of pre-existing infractions.

Edit: nvm, we probably don't want a linter because these errors wouldn't be tied to a push and would start failing randomly.

Comment 2

[Sylvestre Ledru [:Sylvestre]]

Dup of bug 1737307 ?

$ ./mach doc --linkcheck
should do this job

Comment 3

[Andrew Halberstadt [:ahal]]

Oh cool, I missed that!

Let's turn this bug to be about explicitly catching broken links in CI somehow. I've edited the title to reflect this.