doc: Add automodule to command line references

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

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
+   :ref: artiq.frontend.artiq_browser.get_argparser
-   :prog: artiq_session
+   :prog: artiq_browser
    :nodefault:
+   

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 <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:
+   :nodescription:
-
-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
    :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
+   :ref: artiq.frontend.aqctl_corelog.get_argparser
-   :prog: artiq_route
+   :prog: aqctl_corelog
    :nodefault:
+