doc: Add reference descriptions

doc/manual/main_frontend_tools.rst

@@ -46,6 +46,8 @@ These are the top-level commands used to run and manage ARTIQ experiments. Not a
    :prog: artiq_dashboard
    :nodefault:
 
+.. _frontend-artiq-browser:
+
 :mod:`artiq.frontend.artiq_browser`
 -----------------------------------
 
@@ -59,17 +61,28 @@ These are the top-level commands used to run and manage ARTIQ experiments. Not a
 -----------------------------------
 
 .. automodule:: artiq.frontend.artiq_session
+
+ARTIQ session manager. Automatically runs the master, dashboard and local controller manager on the current machine. The latter requires the ``artiq-comtools`` package to be installed. Requires access to device database, for the sake of the master.
+
+When supplying arguments to individual front-end tools, use ``=`` to avoid ambiguity in argument parsing, e.g.: ::
+
+   artiq_session -m=-g -m=--device-db=alternate_device_db.py -c=-v
+
+and so on.
+
 .. argparse::
    :ref: artiq.frontend.artiq_session.get_argparser
    :prog: artiq_session
+   :nodescription:
    :nodefault:
 
 :mod:`artiq_comtools.artiq_ctlmgr`
 ----------------------------------
 
-ARTIQ controller manager. Supplied in the separate package ``artiq-comtools``, which is included with a standard ARTIQ installation but can also be `installed standalone <https://github.com/m-labs/artiq-comtools>`_, with the intention of making it easier to run controllers and controller managers on machines where a full ARTIQ installation may not be necessary or convenient.
-
 .. automodule:: artiq_comtools.artiq_ctlmgr
+
+ARTIQ controller manager. Supplied in the separate package ``artiq-comtools``, which is included with a standard ARTIQ installation but can also be `installed standalone <https://github.com/m-labs/artiq-comtools>`_, with the intention of making it easier to run controllers and controller managers on machines where a full ARTIQ installation may not be necessary or convenient. Requires the master to be running.
+
 .. argparse::
    :ref: artiq_comtools.artiq_ctlmgr.get_argparser
    :prog: artiq_ctlmgr

doc/manual/utilities.rst

@@ -56,10 +56,10 @@ Compiles key/value pairs (e.g. configuration information) into a binary image su
 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
 
+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.
+
 .. argparse::
    :ref: artiq.frontend.artiq_flash.get_argparser
    :prog: artiq_flash
@@ -103,10 +103,10 @@ This tool generates a basic template for a :ref:`device database <device-db>` gi
 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
 
+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`.
+
 .. argparse::
    :ref: artiq.frontend.artiq_rtiomap.get_argparser
    :prog: artiq_rtiomap
@@ -148,12 +148,17 @@ ARTIQ RTIO monitor
 
 .. automodule:: artiq.frontend.artiq_rtiomon
 
+Command-line interface for monitoring RTIO channels, as in the Monitor capacity of dashboard MonInj.
+
 .. argparse::
    :ref: artiq.frontend.artiq_rtiomon.get_argparser
    :prog: artiq_rtiomon
+   :nodescription:
    :nodefault:
 
-Moninj proxy
+.. _utilities-ctrls:
+
+MonInj proxy
 ------------
 
 .. automodule:: artiq.frontend.aqctl_moninj_proxy
@@ -168,12 +173,9 @@ 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::
    :ref: artiq.frontend.aqctl_coreanalyzer_proxy.get_argparser
    :prog: aqctl_coreanalyzer_proxy
-   :nodescription:
    :nodefault:
 
 Core device logging controller
@@ -184,5 +186,4 @@ Core device logging controller
 .. argparse::
    :ref: artiq.frontend.aqctl_corelog.get_argparser
    :prog: aqctl_corelog
-   :nodefault:
+   :nodefault:
-