From ec10d2194c3aa9df25a14396f339b5eb2d936b04 Mon Sep 17 00:00:00 2001 From: Dane Finlay Date: Thu, 27 Dec 2018 17:50:30 +1100 Subject: [PATCH] Add docs on dragonfly's text input engine and command-line interface This commit also adds sphinx-argparse as a documentation requirement and adjusts a few files to make it generate nice documentation from dragonfly/__main__.py. --- documentation/cli.txt | 32 ++++++++++++++++++++++ documentation/conf.py | 2 +- documentation/engines.txt | 3 ++ documentation/miscellaneous.txt | 1 + documentation/requirements.txt | 1 + dragonfly/__main__.py | 24 +++++++++------- dragonfly/engines/backend_text/__init__.py | 18 ++++++++++++ 7 files changed, 70 insertions(+), 11 deletions(-) create mode 100644 documentation/cli.txt diff --git a/documentation/cli.txt b/documentation/cli.txt new file mode 100644 index 0000000..a6fe0bc --- /dev/null +++ b/documentation/cli.txt @@ -0,0 +1,32 @@ + +.. _RefCLI: + +Command-line Interface (CLI) +============================================================================ + +.. argparse:: + :module: dragonfly.__main__ + :func: make_arg_parser + + +Usage Examples +---------------------------------------------------------------------------- +Below are some examples using the *test* sub-command. All of them should +work in Bash. + +.. code:: shell + + # Load a command module and mimic two commands separately. + echo "command one\n command two" | python -m dragonfly test module.py + + # Same test without the pipe. + python -m dragonfly test module.py + command one + command two + + # Same test with quieter output. + echo "command one\n command two" | python -m dragonfly test -q module.py + + # Test loading two modules with the sphinx engine and exit without + # checking input. + python -m dragonfly test -e sphinx --no-input module1.py module2.py diff --git a/documentation/conf.py b/documentation/conf.py index 94b367f..3ea2680 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -45,7 +45,7 @@ def __getattr__(cls, name): #--------------------------------------------------------------------------- # General configuration -extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode"] +extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinxarg.ext"] templates_path = ["templates"] source_suffix = ".txt" master_doc = "index" diff --git a/documentation/engines.txt b/documentation/engines.txt index eb9a792..e65eeb2 100644 --- a/documentation/engines.txt +++ b/documentation/engines.txt @@ -41,6 +41,9 @@ Engine backends .. automodule:: dragonfly.engines.backend_sphinx :members: +.. automodule:: dragonfly.engines.backend_text + :members: + Dictation container classes ---------------------------------------------------------------------------- diff --git a/documentation/miscellaneous.txt b/documentation/miscellaneous.txt index 9c93f09..bf26c41 100644 --- a/documentation/miscellaneous.txt +++ b/documentation/miscellaneous.txt @@ -7,5 +7,6 @@ Contents: .. toctree:: config ccr + cli language windows diff --git a/documentation/requirements.txt b/documentation/requirements.txt index 2865795..17e76bc 100644 --- a/documentation/requirements.txt +++ b/documentation/requirements.txt @@ -1,3 +1,4 @@ mock pyperclip>=1.7.0 six +sphinx-argparse diff --git a/dragonfly/__main__.py b/dragonfly/__main__.py index f5802f8..0b71f17 100644 --- a/dragonfly/__main__.py +++ b/dragonfly/__main__.py @@ -21,6 +21,8 @@ def test_with_engine(args): return 1 # Set the logging level of the root logger. + if args.quiet: + args.log_level = "WARNING" logging.root.setLevel(getattr(logging, args.log_level)) # Connect to the engine, load grammar modules, take input from stdin and @@ -74,7 +76,7 @@ def test_with_engine(args): } -def main(): +def make_arg_parser(): parser = argparse.ArgumentParser( prog="python -m dragonfly", description="Command-line interface to the Dragonfly speech " @@ -85,9 +87,9 @@ def main(): # Create the parser for the "test" command. parser_test = subparsers.add_parser( "test", - help="""Load grammars from Python files for testing with a - dragonfly engine. By default input from stdin is passed to - engine.mimic() after command modules are loaded.""" + help="Load grammars from Python files for testing with a " + "dragonfly engine. By default input from stdin is passed to " + "engine.mimic() after command modules are loaded." ) parser_test.add_argument( "files", metavar="file", nargs="+", type=argparse.FileType("r"), @@ -95,12 +97,12 @@ def main(): ) parser_test.add_argument( "-e", "--engine", default="text", - help="Name of the engine to use for testing. (default: text)" + help="Name of the engine to use for testing." ) parser_test.add_argument( "-l", "--log-level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], - help="Log level to use. (default: WARNING)" + help="Log level to use." ) parser_test.add_argument( "-n", "--no-input", default=False, action="store_true", @@ -112,12 +114,13 @@ def main(): help="Equivalent to '-l WARNING' -- suppresses INFO and DEBUG " "logging." ) + return parser + +def main(): # Parse the arguments and get the relevant function. Exit if the command # is not implemented. - args = parser.parse_args() - if args.quiet: - args.log_level = "WARNING" + args = make_arg_parser().parse_args() def not_implemented(_): print("Command '%s' is not implemented" % args.subparser_name) @@ -130,4 +133,5 @@ def not_implemented(_): exit(return_code) -main() +if __name__ == '__main__': + main() diff --git a/dragonfly/engines/backend_text/__init__.py b/dragonfly/engines/backend_text/__init__.py index 85d15f2..52f2697 100644 --- a/dragonfly/engines/backend_text/__init__.py +++ b/dragonfly/engines/backend_text/__init__.py @@ -22,6 +22,24 @@ SR back-end package for the text input engine ============================================================================ +The text input engine is a convenient, always available implementation +designed to be used via the :meth:`engine.mimic` method. + +To initialise the text input engine, do the following:: + + get_engine("text") + +Note that :meth:`dragonfly.engines.get_engine` called without ``"text"`` +will **never** initialise the text input engine. This is because real speech +recognition backends should be returned from the function by default. + +All dragonfly elements and rule classes should be supported. Use all +uppercase words to mimic input for :class:`Dictation` elements, e.g. +`"find SOME TEXT"` to match the dragonfly spec `"find "`. + +Dragonfly's command-line interface can be used to test command modules with +the text input engine. See the :ref:`CLI page ` for more details. + """ import logging