jugglinmike ddf4d4c288 Bug 1557103 [wpt PR 17189] - [docs] Generate linting docs from source, a=testonly ...

Automatic update from web-platform-tests
[docs] Generate linting docs from source (#17189)

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
--

wpt-commits: 204072e843f69e3a13628c01a928ea99aebed978
wpt-pr: 17189

2019-11-29 10:56:26 +00:00

0 lines

Python

Raw Blame History