Bug 1554416 [wpt PR 16851] - [docs] Automatically generate CLI documentation, a=testonly

Automatic update from web-platform-tests
[docs] Automatically generate CLI documentation (#16851)

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

wp5At-commits: 3149a4323132331e0179d85fdcf35b13c5df9f2f
wpt-pr: 16851

testing/web-platform/tests/docs/conf.py

@@ -12,9 +12,12 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-#import os
-#import sys
-#sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('../tools/wptserve'))
+sys.path.insert(0, os.path.abspath('../tools'))
+import localpaths
 
 # -- Project information -----------------------------------------------------
 
@@ -38,7 +41,8 @@ release = u''
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'recommonmark'
+    'recommonmark',
+    'sphinxarg.ext'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

testing/web-platform/tests/docs/requirements.txt

@@ -1,2 +1,3 @@
 recommonmark==0.5.0
 Sphinx==1.8.5
+sphinx-argparse==0.2.5

testing/web-platform/tests/docs/running-tests/command-line-arguments.md

@@ -0,0 +1,14 @@
+# Command-Line Arguments
+
+The `wpt` command-line application offers a number of features for interacting
+with WPT. The functionality is organized into "sub-commands", and each accepts
+a different set of command-line arguments.
+
+This page documents all of the available sub-commands and associated arguments.
+
+```eval_rst
+.. argparse::
+   :module: tools.wpt.wpt
+   :func: create_complete_parser
+   :prog: wpt
+```

testing/web-platform/tests/docs/running-tests/from-local-system.md

@@ -97,6 +97,9 @@ customising the test run:
 
     ./wpt run --help
 
+[A complete listing of the command-line arguments is available
+here](command-line-arguments).
+
 Additional browser-specific documentation:
 
 ```eval_rst

testing/web-platform/tests/tools/wpt/wpt.py

@@ -80,6 +80,34 @@ def import_command(prog, command, props):
     return script, parser
 
 
+def create_complete_parser():
+    """Eagerly load all subparsers. This involves more work than is required
+    for typical command-line usage. It is maintained for the purposes of
+    documentation generation as implemented in WPT's top-level `/docs`
+    directory."""
+
+    commands = load_commands()
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers()
+
+    for command in commands:
+        props = commands[command]
+
+        if props["virtualenv"]:
+            setup_virtualenv(None, False, props)
+
+        subparser = import_command('wpt', command, props)[1]
+        if not subparser:
+            continue
+
+        subparsers.add_parser(command,
+                              help=props["help"],
+                              add_help=False,
+                              parents=[subparser])
+
+    return parser
+
+
 def setup_virtualenv(path, skip_venv_setup, props):
     if skip_venv_setup and path is None:
         raise ValueError("Must set --venv when --skip-venv-setup is used")