1554416 - [wpt-sync] Sync PR 16851 - [docs] Automatically generate CLI documentation

Status: RESOLVED FIXED

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

Description

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

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

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

Mike Pennisi <[e-mail]> wrote:

[docs] Automatically generate CLI documentation

Command-line usage information was previously only available to users
who had successfully installed wptrunner. Consuming the information in
that form (e.g. navigating between sub-commands, scrolling through pages
of content and searching for keywords) also required some proficiency
with the command-line.

Extend the documentation build process to include this information in
the project website. This makes it easier to consume for those with
limited experience using the command-line, and in particular, it adds
the content to the data indexed by the website's "search" feature.

Because this content is generated from the state of the interface, it
avoids the need to maintain documentation separately.

This is implemented via a new code path that eagerly load wptrunner's
complete command-line interface. The new create_complete_parser is
consumed by the sphinx-argparse module to produce the rendered
documentation.

---

Previously discussed in https://github.com/bocoup/wpt-docs/pull/12

The wptrunner CLI is built lazily based on the subcommand being executed. Even then, the task of argument parsing is split across unrelated argparse instances. These two details resist documentation generation (at least in the terms expected by the sphinx-argparse module).

Facilitating this work required an artificial code path. I'm sensitive to creating branches that aren't used by contributors, but given the small size of the new function, I think the documentation may be valuable enough to justify the maintenance burden.

Here's what the new page looks like:

Like any other content on the Sphinx-powered site, it is indexed by the client-side "search" feature.

And the user's query is highlighted on the page itself

Comment 1

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

PR 16851 applied with additional changes from upstream: 825f7f95c17742cc69068abc3ccc32f373b8a67f, 79bf4fc70ce1e3e1c584ab89b3650e7917b56db7, a2db8f3535102c8c30082f1dfd7b4d1963aa30fe, 089b24085ad1f29ddff341682c4a453044f2f74f, 02d56b7c166590601d8168dbd4e0e92532552abf, 970437d5648288c44152eaa4e8a73e247d343bca

Comment 2

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

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

Comment 3

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/mozilla-inbound/rev/d05018af27ac
[wpt PR 16851] - [docs] Automatically generate CLI documentation, a=testonly

Comment 4

[Arthur Iakab [arthur_iakab]]

https://hg.mozilla.org/mozilla-central/rev/d05018af27ac