doc: CCBs, applet setup from experiment

sbourdeauducq · sbourdeauducq · commit 82fbd3e9c9e1 · 2016-09-09T23:25:29.000+08:00
diff --git a/artiq/dashboard/applets_ccb.py b/artiq/dashboard/applets_ccb.py
@@ -142,6 +142,31 @@ def locate_applet(self, name, group, create_groups):
         return parent, applet
 
     def ccb_create_applet(self, name, command, group=None, code=None):
+        """Requests the creation of a new applet.
+
+        An applet is identified by its name and an optional list of groups that
+        represent a path (nested groups). If ``group`` is a string, it
+        corresponds to a single group. If ``group`` is ``None`` or an empty
+        list, it corresponds to the root.
+
+        ``command`` gives the command line used to run the applet, as if it
+        was started from a shell. The dashboard substitutes variables such as
+        ``$python`` that gives the complete file name of the Python
+        interpreter running the dashboard.
+
+        If the name already exists (after following any specified groups), the
+        command or code of the existing applet with that name is replaced, and
+        the applet is shown at its previous position. If not, a new applet
+        entry is created and the applet is shown at any position on the screen.
+
+        If the group(s) do not exist, they are created.
+
+        If ``code`` is not ``None``, it should be a string that contains the
+        full source code of the applet. In this case, ``command`` is used to
+        specify (optional) command-line arguments to the applet.
+
+        This function is called when a CCB ``create_applet`` is issued.
+        """
         if group is None:
             group = []
         elif isinstance(group, str):
@@ -163,6 +188,13 @@ def ccb_create_applet(self, name, command, group=None, code=None):
             applet.setCheckState(0, QtCore.Qt.Checked)
 
     def ccb_disable_applet(self, name, group=None):
+        """Disables an applet.
+
+        The applet is identified by its name, after following any specified
+        groups.
+
+        This function is called when a CCB ``disable_applet`` is issued.
+        """
         if group is None:
             group = []
         elif isinstance(group, str):
@@ -176,6 +208,13 @@ def ccb_disable_applet(self, name, group=None):
             applet.setCheckState(0, QtCore.Qt.Unchecked)
 
     def ccb_disable_applet_group(self, group):
+        """Disables all the applets in a group.
+
+        If the group is nested, ``group`` should be a list, with the names
+        of the parents preceding the name of the group to disable.
+
+        This function is called when a CCB ``disable_applet_group`` is issued.
+        """
         if isinstance(group, str):
             group = [group]
 
diff --git a/doc/manual/management_system.rst b/doc/manual/management_system.rst
@@ -124,6 +124,16 @@ The scheduler virtual device also contains the attributes ``rid``, ``pipeline_na
 .. autoclass:: artiq.master.scheduler.Scheduler
    :members:
 
+Client control broadcasts (CCBs)
+********************************
+
+Client control broadcasts are requests made by experiments for clients to perform some action. Experiments do so by requesting the ``ccb`` virtual device and calling its ``issue`` method. The first argument of the issue method is the name of the broadcast, and any further positional and keyword arguments are passed to the broadcast.
+
+CCBs are used by experiments to configure applets in the dashboard, for example for plotting purposes.
+
+.. autoclass:: artiq.dashboard.applets_ccb.AppletsCCBDock
+   :members:
+
 Front-end tool reference
 ************************
 
