From 9fb42e49529e01974cab3248379aca383aa50231 Mon Sep 17 00:00:00 2001 From: Sebastien Bourdeauducq Date: Fri, 23 Jan 2015 00:52:13 +0800 Subject: [PATCH] doc: use sphinx-argparse --- artiq/frontend/artiq_client.py | 6 +++--- artiq/frontend/artiq_ctlid.py | 6 +++--- artiq/frontend/artiq_gui.py | 6 +++--- artiq/frontend/artiq_master.py | 6 +++--- artiq/frontend/artiq_run.py | 6 +++--- artiq/frontend/lda_client.py | 14 ++++++++------ artiq/frontend/lda_controller.py | 8 +++++--- artiq/frontend/pdq2_client.py | 6 +++--- artiq/frontend/pdq2_controller.py | 6 +++--- doc/manual/conf.py | 3 ++- doc/manual/drivers_reference.rst | 15 +++++++++++++++ doc/manual/index.rst | 2 ++ doc/manual/management_system.rst | 23 +++++++++++++++++++++++ doc/manual/protocols_reference.rst | 4 ++-- doc/manual/utilities.rst | 16 ++++++++++++++++ setup.py | 2 +- 16 files changed, 95 insertions(+), 34 deletions(-) create mode 100644 doc/manual/management_system.rst create mode 100644 doc/manual/utilities.rst diff --git a/artiq/frontend/artiq_client.py b/artiq/frontend/artiq_client.py index a77938ba0..4dc47a252 100755 --- a/artiq/frontend/artiq_client.py +++ b/artiq/frontend/artiq_client.py @@ -19,7 +19,7 @@ def clear_screen(): sys.stdout.write("\x1b[2J\x1b[H") -def _get_args(): +def get_argparser(): parser = argparse.ArgumentParser(description="ARTIQ CLI client") parser.add_argument( "-s", "--server", default="::1", @@ -80,7 +80,7 @@ def _get_args(): "what", help="select object to show: queue/timed/devices/parameters") - return parser.parse_args() + return parser def _parse_arguments(arguments): @@ -226,7 +226,7 @@ def _show_dict(args, notifier_name, display_fun): def main(): - args = _get_args() + args = get_argparser().parse_args() action = args.action.replace("-", "_") if action == "show": if args.what == "queue": diff --git a/artiq/frontend/artiq_ctlid.py b/artiq/frontend/artiq_ctlid.py index 55f260055..4219f04a4 100755 --- a/artiq/frontend/artiq_ctlid.py +++ b/artiq/frontend/artiq_ctlid.py @@ -5,18 +5,18 @@ import argparse from artiq.protocols.pc_rpc import Client -def _get_args(): +def get_argparser(): parser = argparse.ArgumentParser( description="ARTIQ controller identification tool") parser.add_argument("server", help="hostname or IP of the controller to connect to") parser.add_argument("port", type=int, help="TCP port to use to connect to the controller") - return parser.parse_args() + return parser def main(): - args = _get_args() + args = get_argparser().parse_args() remote = Client(args.server, args.port, None) try: target_names, id_parameters = remote.get_rpc_id() diff --git a/artiq/frontend/artiq_gui.py b/artiq/frontend/artiq_gui.py index c2599fe95..4a25b5464 100755 --- a/artiq/frontend/artiq_gui.py +++ b/artiq/frontend/artiq_gui.py @@ -13,7 +13,7 @@ from artiq.gui.parameters import ParametersWindow from artiq.gui.rt_results import RTResults -def _get_args(): +def get_argparser(): parser = argparse.ArgumentParser(description="ARTIQ GUI client") parser.add_argument( "-s", "--server", default="::1", @@ -24,11 +24,11 @@ def _get_args(): parser.add_argument( "--port-control", default=3251, type=int, help="TCP port to connect to for control") - return parser.parse_args() + return parser def main(): - args = _get_args() + args = get_argparser().parse_args() asyncio.set_event_loop_policy(gbulb.GtkEventLoopPolicy()) loop = asyncio.get_event_loop() diff --git a/artiq/frontend/artiq_master.py b/artiq/frontend/artiq_master.py index 044b7b6b6..a44fcd913 100755 --- a/artiq/frontend/artiq_master.py +++ b/artiq/frontend/artiq_master.py @@ -11,7 +11,7 @@ from artiq.master.scheduler import Scheduler from artiq.master.rt_results import RTResults -def _get_args(): +def get_argparser(): parser = argparse.ArgumentParser(description="ARTIQ master") parser.add_argument( "--bind", default="::1", @@ -22,11 +22,11 @@ def _get_args(): parser.add_argument( "--port-control", default=3251, type=int, help="TCP port to listen to for control") - return parser.parse_args() + return parser def main(): - args = _get_args() + args = get_argparser().parse_args() ddb = FlatFileDB("ddb.pyon") pdb = FlatFileDB("pdb.pyon") diff --git a/artiq/frontend/artiq_run.py b/artiq/frontend/artiq_run.py index 4f5ff437c..cea992fe2 100755 --- a/artiq/frontend/artiq_run.py +++ b/artiq/frontend/artiq_run.py @@ -31,7 +31,7 @@ class SimpleParamLogger: print("Parameter change: {} -> {}".format(name, value)) -def _get_args(): +def get_argparser(): parser = argparse.ArgumentParser( description="Local experiment running tool") @@ -49,7 +49,7 @@ def _get_args(): parser.add_argument("arguments", nargs="*", help="run arguments") - return parser.parse_args() + return parser def _parse_arguments(arguments): @@ -61,7 +61,7 @@ def _parse_arguments(arguments): def main(): - args = _get_args() + args = get_argparser().parse_args() ddb = FlatFileDB(args.ddb) pdb = FlatFileDB(args.pdb) diff --git a/artiq/frontend/lda_client.py b/artiq/frontend/lda_client.py index bcfc4712f..c0555a2d5 100755 --- a/artiq/frontend/lda_client.py +++ b/artiq/frontend/lda_client.py @@ -5,18 +5,20 @@ import argparse from artiq.protocols.pc_rpc import Client -def main(): +def get_argparser(): parser = argparse.ArgumentParser() - parser.add_argument('-s', '--server', default="::1", + parser.add_argument("-s", "--server", default="::1", help="hostname or IP of the controller to connect to") - parser.add_argument('-p', '--port', default=3253, type=int, + parser.add_argument("-p", "--port", default=3253, type=int, help="TCP port to use to connect to the controller") - parser.add_argument('-a', '--attenuation', type=float, + parser.add_argument("-a", "--attenuation", type=float, help="attenuation value to set") - args = parser.parse_args() + return parser + +def main(): + args = get_argparser().parse_args() remote = Client(args.server, args.port, "lda") - try: if args.attenuation is None: print("Current attenuation: {}".format(remote.get_attenuation())) diff --git a/artiq/frontend/lda_controller.py b/artiq/frontend/lda_controller.py index 03e94fd99..a19c8c308 100755 --- a/artiq/frontend/lda_controller.py +++ b/artiq/frontend/lda_controller.py @@ -6,7 +6,7 @@ from artiq.devices.lda.driver import Lda, Ldasim from artiq.protocols.pc_rpc import simple_server_loop -def main(): +def get_argparser(): parser = argparse.ArgumentParser() parser.add_argument('-d', '--device', default="LDA-102", choices=["LDA-102", "LDA-602", "sim"]) @@ -16,13 +16,15 @@ def main(): help="TCP port to listen to") parser.add_argument('-s', '--serial', default=None, help="USB serial number of the device") - args = parser.parse_args() + return parser + +def main(): + args = get_argparser().parse_args() if args.device == "sim": lda = Ldasim() else: lda = Lda(args.serial, args.device) - simple_server_loop({"lda": lda}, args.bind, args.port) diff --git a/artiq/frontend/pdq2_client.py b/artiq/frontend/pdq2_client.py index d30405af9..d5e587a4f 100755 --- a/artiq/frontend/pdq2_client.py +++ b/artiq/frontend/pdq2_client.py @@ -11,7 +11,7 @@ import numpy as np from artiq.protocols.pc_rpc import Client -def _get_args(): +def get_argparser(): parser = argparse.ArgumentParser(description="""PDQ2 client. Evaluates times and voltages, interpolates and uploads them to the controller.""") @@ -49,11 +49,11 @@ def _get_args(): action="store_true", help="do reset before") parser.add_argument("-b", "--bit", default=False, action="store_true", help="do bit test") - return parser.parse_args() + return parser def main(): - args = _get_args() + args = get_argparser().parse_args() dev = Client(args.server, args.port, "pdq2") dev.init() diff --git a/artiq/frontend/pdq2_controller.py b/artiq/frontend/pdq2_controller.py index 0c4aa5677..ad28ac504 100755 --- a/artiq/frontend/pdq2_controller.py +++ b/artiq/frontend/pdq2_controller.py @@ -7,7 +7,7 @@ from artiq.devices.pdq2.driver import Pdq2 from artiq.protocols.pc_rpc import simple_server_loop -def _get_args(): +def get_argparser(): parser = argparse.ArgumentParser(description="PDQ2 controller") parser.add_argument("--bind", default="::1", help="hostname or IP address to bind to") @@ -19,11 +19,11 @@ def _get_args(): parser.add_argument( "-d", "--debug", default=False, action="store_true", help="debug communications") - return parser.parse_args() + return parser def main(): - args = _get_args() + args = get_argparser().parse_args() if args.debug: logging.basicConfig(level=logging.DEBUG) diff --git a/doc/manual/conf.py b/doc/manual/conf.py index 3a1192410..02a3adf23 100644 --- a/doc/manual/conf.py +++ b/doc/manual/conf.py @@ -32,6 +32,7 @@ import os extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.mathjax', + 'sphinxarg.ext', ] # Add any paths that contain templates here, relative to this directory. @@ -48,7 +49,7 @@ master_doc = 'index' # General information about the project. project = 'ARTIQ' -copyright = '2014, M-Labs / NIST Ion Storage Group' +copyright = '2014-2015, M-Labs / NIST Ion Storage Group' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/doc/manual/drivers_reference.rst b/doc/manual/drivers_reference.rst index e620966d8..cfa06cf5b 100644 --- a/doc/manual/drivers_reference.rst +++ b/doc/manual/drivers_reference.rst @@ -17,6 +17,13 @@ Each driver is run in a separate "controller" that exposes a RPC interface (base .. automodule:: artiq.devices.pdq2 :members: +.. argparse:: + :ref: artiq.frontend.pdq2_controller.get_argparser + :prog: pdq2_controller + +.. argparse:: + :ref: artiq.frontend.pdq2_client.get_argparser + :prog: pdq2_client :mod:`artiq.devices.lda` module --------------------------------- @@ -24,6 +31,14 @@ Each driver is run in a separate "controller" that exposes a RPC interface (base .. automodule:: artiq.devices.lda.driver :members: +.. argparse:: + :ref: artiq.frontend.lda_controller.get_argparser + :prog: lda_controller + + +.. argparse:: + :ref: artiq.frontend.lda_client.get_argparser + :prog: lda_client Default TCP port list --------------------- diff --git a/doc/manual/index.rst b/doc/manual/index.rst index d7e039d3b..75ded1ff5 100644 --- a/doc/manual/index.rst +++ b/doc/manual/index.rst @@ -9,8 +9,10 @@ Contents: installing getting_started writing_a_driver + management_system core_language_reference core_drivers_reference protocols_reference drivers_reference + utilities fpga_board_ports diff --git a/doc/manual/management_system.rst b/doc/manual/management_system.rst new file mode 100644 index 000000000..f70166990 --- /dev/null +++ b/doc/manual/management_system.rst @@ -0,0 +1,23 @@ +Management system +================= + +Master +------ + +.. argparse:: + :ref: artiq.frontend.artiq_master.get_argparser + :prog: artiq_master + +Command-line client +------------------- + +.. argparse:: + :ref: artiq.frontend.artiq_client.get_argparser + :prog: artiq_client + +GUI client +---------- + +.. argparse:: + :ref: artiq.frontend.artiq_gui.get_argparser + :prog: artiq_gui diff --git a/doc/manual/protocols_reference.rst b/doc/manual/protocols_reference.rst index df6e00491..070176acd 100644 --- a/doc/manual/protocols_reference.rst +++ b/doc/manual/protocols_reference.rst @@ -1,5 +1,5 @@ -Management reference -==================== +Protocols reference +=================== :mod:`artiq.protocols.asyncio_server` module -------------------------------------------- diff --git a/doc/manual/utilities.rst b/doc/manual/utilities.rst new file mode 100644 index 000000000..cef4cfffb --- /dev/null +++ b/doc/manual/utilities.rst @@ -0,0 +1,16 @@ +Utilities +========= + +Local running tool +------------------ + +.. argparse:: + :ref: artiq.frontend.artiq_run.get_argparser + :prog: artiq_run + +Controller identification tool +------------------------------ + +.. argparse:: + :ref: artiq.frontend.artiq_ctlid.get_argparser + :prog: artiq_ctlid diff --git a/setup.py b/setup.py index 335bceba8..ffae9b2b1 100755 --- a/setup.py +++ b/setup.py @@ -15,7 +15,7 @@ setup( long_description=open("README.rst").read(), license="BSD", install_requires=[ - "sphinx", "pyserial", "numpy", "scipy", "prettytable" + "sphinx", "sphinx-argparse", "pyserial", "numpy", "scipy", "prettytable" ], extras_require={}, dependency_links=[],