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

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

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"

documentation/engines.txt

@@ -41,6 +41,9 @@ Engine backends
 .. automodule:: dragonfly.engines.backend_sphinx
    :members:
 
+.. automodule:: dragonfly.engines.backend_text
+   :members:
+
 
 Dictation container classes
 ----------------------------------------------------------------------------

documentation/miscellaneous.txt

@@ -7,5 +7,6 @@ Contents:
 .. toctree::
    config
    ccr
+   cli
    language
    windows

documentation/requirements.txt

@@ -1,3 +1,4 @@
 mock
 pyperclip>=1.7.0
 six
+sphinx-argparse

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,22 +87,22 @@ 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"),
         help="Command module file(s)."
     )
     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()

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 <text>"`.
+
+Dragonfly's command-line interface can be used to test command modules with
+the text input engine. See the :ref:`CLI page <RefCLI>` for more details.
+
 """
 
 import logging