1557103 - [wpt-sync] Sync PR 17189 - [docs] Generate linting docs from source

Status: RESOLVED FIXED

(Testing :: web-platform-tests, defect, P4)

Description

[Web Platform Test Sync Bot (Matrix: #interop:mozilla.org)]

Sync web-platform-tests PR 17189 into mozilla-central (this bug is closed when the sync is complete).

PR: https://github.com/web-platform-tests/wpt/pull/17189
Details from upstream follow.

Mike Pennisi <[e-mail]> wrote:

[docs] Generate linting docs from source

When new rules have been added to WPT's "lint" tool, the corresponding
documentation has not always been updated [1] [2] [3]. The static list
of rules currently describes only 22 of the 53 available rules.
Automatically generating documentation from source code helps avoid this
state and the confusion it can cause contributors.

Rely on the previously-implemented source code structure [4] during
documentation generation to automatically create a listing of all
available linting rules.

Although the Sphinx documentation generator includes a built-in
extension for generating documentation from Python source code, the
output of that extension is designed to document Python primitives such
as functions and classes. Such a format is inappropriate for this case
because the users of the linting tool do not interact with the internals
in this way. Define a custom docutils directive to tailor the
documentation to the needs of its audience.

[1] https://github.com/web-platform-tests/wpt/issues/5299
[2] https://github.com/web-platform-tests/wpt/issues/10501
[3] https://github.com/web-platform-tests/wpt/issues/11479
[4] https://github.com/web-platform-tests/wpt/pull/16268

---

As noted in the commit message, this nearly doubles the number of documented
linting rules. Over time, we can further improve it by separating out explicit
"to fix" instructions (and maybe even require that new rules do the same).

Comment 1

[Web Platform Test Sync Bot (Matrix: #interop:mozilla.org)]

Pushed to try https://treeherder.mozilla.org/#/jobs?repo=try&revision=f4988b356c3ef6b12ade68c29c99911fc45f8001

Comment 2

[Web Platform Test Sync Bot (Matrix: #interop:mozilla.org)]

Pushed to try https://treeherder.mozilla.org/#/jobs?repo=try&revision=9568ac1af8a50f608e52a14dcb6c0f9178d2964f

Comment 3

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/56fc8b1c2e12
[wpt PR 17189] - [docs] Generate linting docs from source, a=testonly

Comment 4

[Web Platform Test Sync Bot (Matrix: #interop:mozilla.org)]

Test result changes from PR not available.

Comment 5

[Andrei Ciure[:aciure]]

https://hg.mozilla.org/mozilla-central/rev/56fc8b1c2e12