mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-27 12:15:33 +00:00
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
This commit is contained in:
parent
eec4b1ff0a
commit
a65d508901
@ -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.
|
||||
|
@ -1,2 +1,3 @@
|
||||
recommonmark==0.5.0
|
||||
Sphinx==1.8.5
|
||||
sphinx-argparse==0.2.5
|
||||
|
@ -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
|
||||
```
|
@ -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
|
||||
|
@ -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")
|
||||
|
Loading…
Reference in New Issue
Block a user