[docs] Automatically generate CLI documentation

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

docs/requirements.txt

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

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

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

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