diff --git a/artiq/frontend/artiq_client.py b/artiq/frontend/artiq_client.py index 143315046..b0a2345e6 100755 --- a/artiq/frontend/artiq_client.py +++ b/artiq/frontend/artiq_client.py @@ -1,10 +1,4 @@ #!/usr/bin/env python3 -""" -Client to send commands to :mod:`artiq_master` and display results locally. - -The client can perform actions such as accessing/setting datasets, -scanning devices, scheduling experiments, and looking for experiments/devices. -""" import argparse import logging diff --git a/doc/manual/main_frontend_tools.rst b/doc/manual/main_frontend_tools.rst index 8b985d22e..c4ebae287 100644 --- a/doc/manual/main_frontend_tools.rst +++ b/doc/manual/main_frontend_tools.rst @@ -1,11 +1,14 @@ -Main front-end tool reference -============================= +Main front-end tools +==================== These are the top-level commands used to run and manage ARTIQ experiments. Not all of the ARTIQ front-end is described here (many additional useful commands are presented in this manual in :doc:`utilities`) but these together comprise the main points of access for using ARTIQ as a system. -:mod:`artiq.frontend.artiq_run` -------------------------------- +.. Note that ARTIQ frontend has no docstrings and the ..automodule directives display nothing; they are there to make :mod: references function correctly, since sphinx-argparse does not support links to ..argparse directives in the same way. +:mod:`artiq.frontend.artiq_run` +-------------------------------- + +.. automodule:: artiq.frontend.artiq_run .. argparse:: :ref: artiq.frontend.artiq_run.get_argparser :prog: artiq_run @@ -14,8 +17,9 @@ These are the top-level commands used to run and manage ARTIQ experiments. Not a .. _frontend-artiq-master: :mod:`artiq.frontend.artiq_master` ----------------------------------- +----------------------------------- +.. automodule:: artiq.frontend.artiq_master .. argparse:: :ref: artiq.frontend.artiq_master.get_argparser :prog: artiq_master @@ -24,28 +28,30 @@ These are the top-level commands used to run and manage ARTIQ experiments. Not a .. _frontend-artiq-client: :mod:`artiq.frontend.artiq_client` ----------------------------------- - +----------------------------------- +.. automodule:: artiq.frontend.artiq_client .. argparse:: :ref: artiq.frontend.artiq_client.get_argparser :prog: artiq_client :nodefault: - .. _frontend-artiq-dashboard: :mod:`artiq.frontend.artiq_dashboard` ------------------------------------- +.. automodule:: artiq.frontend.artiq_dashboard .. argparse:: :ref: artiq.frontend.artiq_dashboard.get_argparser :prog: artiq_dashboard :nodefault: -:mod:`artiq.frontend.artiq_session` ------------------------------------ +:mod:`artiq.frontend.artiq_browser` +------------------------------------ +.. automodule:: artiq.frontend.artiq_browser .. argparse:: - :ref: artiq.frontend.artiq_session.get_argparser - :prog: artiq_session + :ref: artiq.frontend.artiq_browser.get_argparser + :prog: artiq_browser :nodefault: + \ No newline at end of file diff --git a/doc/manual/utilities.rst b/doc/manual/utilities.rst index 7abfeaaaa..934ef9590 100644 --- a/doc/manual/utilities.rst +++ b/doc/manual/utilities.rst @@ -4,11 +4,15 @@ Utilities .. Sort these tool by some subjective combination of their typical sequence and expected frequency of use. +.. As in main_frontend_reference, automodule directives display nothing and are here to make :mod: links possible + .. _afws-client: ARTIQ Firmware Service (AFWS) client ------------------------------------ +.. automodule:: artiq.frontend.afws_client + This tool serves as a client for building tailored firmware and gateware from M-Lab's servers and downloading the binaries in ready-to-flash format. It is necessary to have a valid subscription to AFWS to use it. Subscription also includes general helpdesk support and can be purchased or extended by contacting ``sales@``. One year of support is included with any Kasli carriers or crates containing them purchased from M-Labs. Additional one-time use is generally provided with purchase of additional cards to facilitate the system configuration change. .. argparse:: @@ -24,7 +28,9 @@ This tool serves as a client for building tailored firmware and gateware from M- Static compiler --------------- -This tool compiles an experiment into a ELF file. It is primarily used to prepare binaries for the startup and idle kernels, loaded in non-volatile storage of the core device. Experiments compiled with this tool are not allowed to use RPCs, and their ``run`` entry point must be a kernel. +.. automodule:: artiq.frontend.artiq_compile + +Compiles an experiment into a ELF file (or a TAR file if the experiment involves subkernels). It is primarily used to prepare binaries for the startup and idle kernels, loaded in non-volatile storage of the core device. Experiments compiled with this tool are not allowed to use RPCs, and their ``run`` entry point must be a kernel. .. argparse:: :ref: artiq.frontend.artiq_compile.get_argparser @@ -35,7 +41,9 @@ This tool compiles an experiment into a ELF file. It is primarily used to prepar Flash storage image generator ----------------------------- -This tool compiles key/value pairs (e.g. configuration information) into a binary image suitable for flashing into the storage space of the core device. It can be used in combination with ``artiq_flash`` to configure the core device, but this is normally necessary at most to set the ``ip`` field; once the core device is reachable by network it is preferable to use ``artiq_coremgmt config``. +.. automodule:: artiq.frontend.artiq_mkfs + +Compiles key/value pairs (e.g. configuration information) into a binary image suitable for flashing into the storage space of the core device. It can be used in combination with ``artiq_flash`` to configure the core device, but this is normally necessary at most to set the ``ip`` field; once the core device is reachable by network it is preferable to use ``artiq_coremgmt config``. Not applicable to ARTIQ-Zynq, where preconfiguration is better achieved by loading ``config.txt`` onto the SD card. .. argparse:: :ref: artiq.frontend.artiq_mkfs.get_argparser @@ -48,9 +56,14 @@ This tool compiles key/value pairs (e.g. configuration information) into a binar Flashing/Loading tool --------------------- +Allows for flashing and loading of various files onto the core device. Not applicable to ARTIQ-Zynq, where gateware and firmware should be loaded onto the core device with :mod:`~artiq.frontend.artiq_coremgmt`, directly copied onto the SD card, or (for developers) using the :ref:`ARTIQ netboot ` utility. + +.. automodule:: artiq.frontend.artiq_flash + .. argparse:: :ref: artiq.frontend.artiq_flash.get_argparser :prog: artiq_flash + :nodescription: :nodefault: .. _core-device-management-tool: @@ -58,9 +71,11 @@ Flashing/Loading tool Core device management tool --------------------------- -The core management utility gives remote access to the core device logs, the :ref:`core-device-flash-storage`, and other management functions. +.. automodule:: artiq.frontend.artiq_coremgmt -To use this tool, it is necessary to specify the IP address your core device can be contacted at. If no option is used, the utility will assume there is a file named ``device_db.py`` in the current directory containing the device database; otherwise, a device database file can be provided with ``--device-db`` or an address directly with ``--device`` (see also below). +The core management utility gives remote access to the core device logs, the :ref:`core device flash storage `, and other management functions. + +To use this tool, it is necessary to specify the IP address your core device can be contacted at. If no option is used, the utility will assume there is a file named ``device_db.py`` in the current directory containing the :ref:`device database `; otherwise, a device database file can be provided with ``--device-db`` or an address directly with ``--device`` (see also below). .. argparse:: :ref: artiq.frontend.artiq_coremgmt.get_argparser @@ -68,38 +83,19 @@ To use this tool, it is necessary to specify the IP address your core device can :nodescription: :nodefault: -Core device logging controller ------------------------------- - -.. argparse:: - :ref: artiq.frontend.aqctl_corelog.get_argparser - :prog: aqctl_corelog - :nodefault: - .. _ddb-template-tool: Device database template generator ---------------------------------- +.. automodule:: artiq.frontend.artiq_ddb_template + +This tool generates a basic template for a :ref:`device database ` given the JSON description file(s) for the system. Entries for :ref:`controllers ` are not generated. + .. argparse:: :ref: artiq.frontend.artiq_ddb_template.get_argparser :prog: artiq_ddb_template - :nodefault: - -ARTIQ RTIO monitor ------------------- - -.. argparse:: - :ref: artiq.frontend.artiq_rtiomon.get_argparser - :prog: artiq_rtiomon - :nodefault: - -Moninj proxy ------------- - -.. argparse:: - :ref: artiq.frontend.aqctl_moninj_proxy.get_argparser - :prog: aqctl_moninj_proxy + :nodescription: :nodefault: .. _rtiomap-tool: @@ -107,9 +103,14 @@ Moninj proxy RTIO channel name map tool -------------------------- +This tool encodes the map of RTIO channel numbers to names in a format suitable for writing to the config key ``device_map``. See :ref:`config-rtiomap`. + +.. automodule:: artiq.frontend.artiq_rtiomap + .. argparse:: :ref: artiq.frontend.artiq_rtiomap.get_argparser :prog: artiq_rtiomap + :nodescription: :nodefault: .. _core-device-rtio-analyzer-tool: @@ -117,7 +118,9 @@ RTIO channel name map tool Core device RTIO analyzer tool ------------------------------ -This tool converts core device RTIO logs to VCD waveform files that are readable by third-party tools such as GtkWave. See :ref:`rtio-analyzer-example` for an example, or ``artiq.test.coredevice.test_analyzer`` for a relevant unit test. When using the ARTIQ dashboard, recorded data can be viewed or exported directly in the integrated waveform analyzer (the "Waveform" dock). +.. automodule:: artiq.frontend.artiq_coreanalyzer + +This tool converts core device RTIO logs to VCD waveform files that are readable by third-party tools such as GtkWave. See :ref:`rtio-analyzer-example` for an example, or :mod:`artiq.test.coredevice.test_analyzer` for a relevant unit test. When using the ARTIQ dashboard, recorded data can be viewed or exported directly in the integrated waveform analyzer (the "Waveform" dock). .. argparse:: :ref: artiq.frontend.artiq_coreanalyzer.get_argparser @@ -127,9 +130,44 @@ This tool converts core device RTIO logs to VCD waveform files that are readable .. _routing-table-tool: +DRTIO routing table manipulation tool +------------------------------------- + +.. automodule:: artiq.frontend.artiq_route + +This tool allows for manipulation of a DRTIO routing table file, which can be transmitted to the core device using :mod:`artiq_coremgmt config write`; see :ref:`drtio-routing`. + +.. argparse:: + :ref: artiq.frontend.artiq_route.get_argparser + :prog: artiq_route + :nodescription: + :nodefault: + +ARTIQ RTIO monitor +------------------ + +.. automodule:: artiq.frontend.artiq_rtiomon + +.. argparse:: + :ref: artiq.frontend.artiq_rtiomon.get_argparser + :prog: artiq_rtiomon + :nodefault: + +Moninj proxy +------------ + +.. automodule:: artiq.frontend.aqctl_moninj_proxy + +.. argparse:: + :ref: artiq.frontend.aqctl_moninj_proxy.get_argparser + :prog: aqctl_moninj_proxy + :nodefault: + Core device RTIO analyzer proxy ------------------------------- +.. automodule:: artiq.frontend.aqctl_coreanalyzer_proxy + This tool distributes the core analyzer dump to several clients such as the dashboard. .. argparse:: @@ -138,10 +176,13 @@ This tool distributes the core analyzer dump to several clients such as the dash :nodescription: :nodefault: -DRTIO routing table manipulation tool -------------------------------------- +Core device logging controller +------------------------------ + +.. automodule:: artiq.frontend.aqctl_corelog .. argparse:: - :ref: artiq.frontend.artiq_route.get_argparser - :prog: artiq_route + :ref: artiq.frontend.aqctl_corelog.get_argparser + :prog: aqctl_corelog :nodefault: +