Command line interface autodoc.

docs/cli.rst

@@ -0,0 +1,28 @@
+Command Line Interface
+======================
+
+
+.. argparse::
+   :ref: simple_rpc.cli._arg_parser
+   :prog: simple_rpc
+
+   Subcommands
+   ===========
+
+
+.. argparse::
+   :ref: simple_rpc.cli._arg_parser
+   :prog: simple_rpc
+   :path: list
+
+   The ``list`` subcommand
+   =======================
+
+
+.. argparse::
+   :ref: simple_rpc.cli._arg_parser
+   :prog: simple_rpc
+   :path: call
+
+   The ``call`` subcommand
+   =======================

docs/conf.py

@@ -1,7 +1,7 @@
 from subprocess import call
 
 # NOTE: Add sphinx_autodoc_typehints when ReadTheDocs supports it.
-call('pip install six ..', shell=True)
+call('pip install six sphinx-argparse ..', shell=True)
 
 from simple_rpc import _get_metadata
 
@@ -13,5 +13,5 @@
 
 autoclass_content = 'both'
 # NOTE: Add sphinx_autodoc_typehints when ReadTheDocs supports it.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinxarg.ext']
 master_doc = 'index'

docs/index.rst

@@ -7,6 +7,7 @@
    introduction
    install
    usage
+   cli
    library
    api
    credits

docs/usage.rst

@@ -32,7 +32,7 @@ To detect serial devices, we recommend using the arduino-cli_ toolkit.
     /dev/ttyACM0 Serial Port (USB) Arduino Mega or Mega 2560 arduino:avr:mega arduino:avr
 
 This command will not detect any devices connected via ethernet or WiFi. Use a
-URL_ (e.g., ``socket://192.168.1.50:10000``) instead.
+URL (e.g., ``socket://192.168.1.50:10000``) instead.
 
 
 Method discovery

simple_rpc/cli.py

@@ -1,4 +1,4 @@
-from argparse import ArgumentParser, FileType, RawDescriptionHelpFormatter
+from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser, FileType
 from json import dumps, loads
 from json.decoder import JSONDecodeError
 from sys import stdout
@@ -82,43 +82,52 @@ def rpc_call(
             handle.write('{}\n'.format(dumps(json_utf8_decode(result))))
 
 
-def main() -> None:
-    """Main entry point."""
+def _arg_parser() -> object:
+    """Command line argument parsing."""
     output_parser = ArgumentParser(add_help=False)
     output_parser.add_argument(
         '-o', dest='handle', metavar='OUTPUT', type=FileType('w'),
-        default=stdout, help='output file')
+        default='-', help='output file')
 
     common_parser = ArgumentParser(add_help=False, parents=[output_parser])
     common_parser.add_argument(
-        'device', metavar='DEVICE', type=str, help='device (%(type)s)')
+        'device', metavar='DEVICE', type=str, help='device')
     common_parser.add_argument(
         '-b', dest='baudrate', type=int, default=9600,
-        help='baud rate (%(type)s default=%(default)s)')
+        help='baud rate')
     common_parser.add_argument(
         '-w', dest='wait', type=int, default=2,
-        help='time before communication starts (%(type)s default=%(default)s)')
+        help='time before communication starts')
 
     parser = ArgumentParser(
-        formatter_class=RawDescriptionHelpFormatter,
+        formatter_class=ArgumentDefaultsHelpFormatter,
         description=usage[0], epilog=usage[1])
     parser.add_argument(
         '-v', action='version', version=version(parser.prog))
     subparsers = parser.add_subparsers(dest='subcommand')
     subparsers.required = True
 
     subparser = subparsers.add_parser(
-        'list', parents=[common_parser], description=doc_split(rpc_list))
+        'list', formatter_class=ArgumentDefaultsHelpFormatter,
+        parents=[common_parser], description=doc_split(rpc_list))
     subparser.set_defaults(func=rpc_list)
 
     subparser = subparsers.add_parser(
-        'call', parents=[common_parser], description=doc_split(rpc_call))
+        'call', formatter_class=ArgumentDefaultsHelpFormatter,
+        parents=[common_parser], description=doc_split(rpc_call))
     subparser.set_defaults(func=rpc_call)
     subparser.add_argument(
         'name', metavar='NAME', type=str, help='command name')
     subparser.add_argument(
         'args', metavar='ARG', type=str, nargs='*', help='command parameter')
 
+    return parser
+
+
+def main() -> None:
+    """Main entry point."""
+    parser = _arg_parser()
+
     try:
         args = parser.parse_args()
     except IOError as error:

simple_rpc/simple_rpc.py

@@ -133,7 +133,7 @@ def call_method(self: object, name: str, *args: list) -> any:
         """Execute a method.
 
         :arg name: Method name.
-        :arg *args: Method parameters.
+        :arg args: Method parameters.
 
         :returns: Return value of the method.
         """