occheung
/
artiq
forked from M-Labs/artiq
1
0
Fork 0
Code Pull Requests Activity

doc: Add automodule to command line references

This commit is contained in:
architeuthidae 2024-07-29 11:31:12 +08:00 committed by Sébastien Bourdeauducq
parent 937f3811d1
commit bac22b7163
3 changed files with 92 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
artiq/frontend/artiq_client.py
View File

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

30
doc/manual/main_frontend_tools.rst
View File

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

107
doc/manual/utilities.rst
View File

@ -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 <zynq-jtag-boot>` 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 <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 <device-db>`; 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 <device-db>` given the JSON description file(s) for the system. Entries for :ref:`controllers <environment-ctlrs>` 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<artiq.frontend.artiq_coremgmt>`; 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: