1878968 - (doc-warnings) [meta] Eliminate all sphinx warnings when building docs

Status: NEW

(Developer Infrastructure :: Source Documentation, task, P3)

Description

[Mark Banner (:standard8)]

This is a continuation of bug 1749473 as a fresh meta bug. When fixing issues, we should deal with them in separate bugs that block this one.

There are currently a lot of warnings (around 800) when running source docs generation (./mach doc). This makes it difficult to know if you're creating new ones, or to find the new ones when comparing logs.

From bug 1749473 comment 0:

Bug 1748845 added a mechanism to allow marking certain warnings as fatal. So the way forward here is to pick a warning, fix all instances of it, and then add that warning to the fatal list. Eventually we hopefully end up with zero warnings and can just get sphinx to fail on any warning instead.

We also now have a limit on the number of warnings, that is at least catching a few instances of developers pushing it above the limit - so we don't necessarily have to pick one at a time, but it might be a good strategy anyway.