Auto-update from Github Actions Workflow

Deployed from commit 6162e0b (refs/tags/v0.11.0) Deployed from commit 6162e0b (refs/tags/v0.11.0)
pcdshub · Aug 20, 2024 · fef5d23 · fef5d23
1 parent b02656e
commit fef5d23
Show file tree

Hide file tree

Showing 61 changed files with 6,329 additions and 3 deletions.
diff --git a/index.html b/index.html
@@ -1,9 +1,9 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <meta http-equiv="Refresh" content="0; url=v0.10.3" />
+    <meta http-equiv="Refresh" content="0; url=v0.11.0" />
   </head>
   <body>
-    <p>Go to the <a href="v0.10.3">default documentation</a>.</p>
+    <p>Go to the <a href="v0.11.0">default documentation</a>.</p>
   </body>
 </html>
diff --git a/v0.11.0/.buildinfo b/v0.11.0/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: d7a42737daddfb705d4adbc2579d4dc6
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/v0.11.0/.nojekyll b/v0.11.0/.nojekyll
diff --git a/v0.11.0/_images/lucid_grid.png b/v0.11.0/_images/lucid_grid.png
diff --git a/v0.11.0/_images/lucid_toolbar.png b/v0.11.0/_images/lucid_toolbar.png
diff --git a/v0.11.0/_images/nomachine_issue.png b/v0.11.0/_images/nomachine_issue.png
diff --git a/v0.11.0/_images/nomachine_settings.png b/v0.11.0/_images/nomachine_settings.png
diff --git a/v0.11.0/_sources/grid.rst.txt b/v0.11.0/_sources/grid.rst.txt
@@ -0,0 +1,88 @@
+Lucid Grid Configuration
+========================
+
+``lucid``'s main grid area is an auto-generated series of buttons and indicators,
+where each indicator represents a device
+loaded from a ``happi`` database.
+
+.. figure:: /_static/lucid_grid.png
+   :scale: 50 %
+   :alt: Lucid display with the grid highlighted.
+
+
+Which Devices are Included?
+---------------------------
+
+When ``lucid`` is invoked, the only required argument is the positional ``beamline`` argument.
+This argument is used as a ``happi`` search term to fill the grid.
+
+This is equivalent to the following search using the ``happi`` command line,
+assuming your beamline is named BEAMLINE:
+
+.. code-block:: bash
+
+    happi search beamline=BEAMLINE active=True
+
+
+All devices that match this search and load without errors will be included in the grid.
+All other devices will be excluded.
+The search is case-sensitive.
+
+Note that inactive devices are not included,
+and that this only targets happi entries that have a beamline associated with them at all.
+This requires the ``happi`` containers defined in ``pcdsdevices``,
+which define the ``beamline`` field.
+
+Note: if you prefer not to load any devices, you can skip this step by passing
+a command-line parameter:
+
+.. code-block:: bash
+
+    lucid --skip_happi MY_BEAMLINE
+
+
+How are the Devices Arranged in the Grid?
+-----------------------------------------
+
+The grid is defined by the various metadata values found in the ``happi`` database.
+The default metadata keys in use are:
+
+- ``location_group``, to select which column to put a device into
+- ``functional_group``, to select with row to put a device into
+
+That is to say, by default we expect the row headers on the left to be functional names like
+"imager" or "vacuum" and column headers on the top to be location names like "Section 01" or "Section 02".
+
+You can change which metadata keys are used by passing the
+``--row_group_key`` and ``--col_group_key`` command-line parameters
+to select the row grouping and column groupings respectively.
+
+Each unique string (case-sensitive) found in the group key metadata for the
+active devices will create an additional row or column in the grid
+with the corresponding header text.
+The rows and the columns will each be sorted in alphabetical order.
+
+Each device indicator will be added to a single square cell in the grid that
+corresponds with its metadata sorting.
+
+This provides the following features:
+
+- An alarm indicator that represents the device's worst alarm state,
+  with mouseover text that will show more precise information
+- The option to click the cell and select the device name to open the device's
+  ``typhos`` screen in the right-hand dock area
+- The option to click the row or column header to select the device name for the
+  same purpose as above, where the devices can be from any cell in the corresponding
+  row or column.
+- The ability to search for devices within the grid using the search bar,
+  which will highlight their indicators in the grid view.
+
+
+Limitations
+-----------
+
+- There are currently no configuration options for row/column ordering or
+  customization of the happi search used to accumulate devices.
+- The only way to adjust the grid is to carefully manipulate the ``happi`` database.
+- There are no options for changing the sizes of cells or the sizes of the alarm
+  indicators held inside the cells.
diff --git a/v0.11.0/_sources/index.rst.txt b/v0.11.0/_sources/index.rst.txt
@@ -0,0 +1,18 @@
+Lucid
+=====
+
+LCLS User Control and Interface Design
+
+.. toctree::
+    :maxdepth: 1
+    :caption: User Documentation
+
+    launcher.rst
+    grid.rst
+    toolbar.rst
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Troubleshooting
+
+    troubleshooting/remote_access.rst
diff --git a/v0.11.0/_sources/launcher.rst.txt b/v0.11.0/_sources/launcher.rst.txt
@@ -0,0 +1,7 @@
+Lucid Launcher Options
+======================
+
+.. argparse::
+    :module: lucid.launcher
+    :func: get_parser
+    :prog: lucid
diff --git a/v0.11.0/_sources/toolbar.rst.txt b/v0.11.0/_sources/toolbar.rst.txt
@@ -0,0 +1,110 @@
+Lucid Toolbar Configuration
+===========================
+
+``lucid`` can be launched with a toolbar file that specifies
+the tabs that are displayed below the device grid.
+These tabs can be configured to hold buttons
+that open other screens.
+
+.. figure:: /_static/lucid_toolbar.png
+   :scale: 50 %
+   :alt: Lucid display with the toolbar highlighted.
+
+Invocation
+----------
+
+The invocation to include this toolbar file is:
+
+.. code-block:: bash
+
+    lucid --toolbar /path/to/toolbar/file.yaml HUTCHNAME
+
+Options and Limitations
+-----------------------
+
+- The user can specify an arbitrary number of tabs.
+- Each tab can have an arbitrary number of columns.
+- The columns are filled from left to right, then from top to bottom.
+- Only ``PyDMShellCommand`` and ``PyDMRelatedDisplayButton`` widgets are supported.
+- Any available pyqt property or general python attribute can be specified on either
+  of these button types.
+
+Guidelines
+----------
+
+- The related display option (``display``) should be used whenever it is possible to do so,
+  because the screen will open more quickly compared to a shell script, which will need to
+  initialize an entire new python shell with new imports.
+
+File Format
+-----------
+
+The toolbar configuration is stored in a yaml file that encodes a dictionary.
+Each key in this top-level dictionary is the name of a tab to include.
+These tabs will be arranged in file order from left to right.
+
+Each of these tab names should contain another dictionary with the following top-level keys:
+
+- ``config`` (optional)
+- ``buttons``
+
+The only ``config`` option right now is ``cols``, which defaults to 4.
+
+Here's an example config file structure, omitting only the ``buttons`` sections:
+
+.. code-block:: yaml
+
+    tab1_name_with_3_cols:
+      config:
+        cols: 3
+      buttons: see below
+    tab2_name_with_2_cols:
+      config:
+        cols: 2
+      buttons: see below
+    tab3_name_with_4_cols:
+      buttons: see below
+
+
+The ``buttons`` key should itself point to a dictionary that maps each
+button text to a button config dictionary, in order.
+LUCID will iterate through these dictionaries and create buttons,
+arranging them from left to right across each column before moving to the next row.
+
+The button config dictionary has one special key: ``type``.
+The ``type`` key can either be ``shell`` to create a ``PyDMShellCommand`` button,
+or it can be ``display`` to create a ``PyDMRelatedDisplayButton``.
+If ``type`` is omitted, or is not one of these options,
+an inactive ``QPushButton`` will be created.
+
+All other keys in the config dictionary should be mappings from qt property names
+to each property's desired value.
+This is forward-compatible with any new properties that may be implemented in the future
+for these button types.
+
+Here's an example buttons config snippit that shows the structure and some of the
+useful properties. This will create two buttons, one with button text "Cool PyDM Display"
+and another with button text "Run Neat Script."
+
+.. code-block:: yaml
+
+    buttons:
+      Cool PyDM Display:
+        type: display
+        filenames:
+          - /path/to/some/ui/file.ui
+        macros:
+          - "{'PREFIX': 'COOL'}"
+      Run Neat Script:
+        type: shell
+        commands:
+          - "echo 'neat'"
+          - /path/to/some/neat/shell/script.sh
+        redirectCommandOutput: true
+
+Examples
+--------
+
+The LCLS lucid toolbar configurations are backed up in
+`this github repo <https://github.com/pcdshub/lucid_config>`_.
+These are all good examples for how to set these files up.
diff --git a/v0.11.0/_sources/troubleshooting/remote_access.rst.txt b/v0.11.0/_sources/troubleshooting/remote_access.rst.txt
@@ -0,0 +1,26 @@
+Remote Access
+=============
+
+NoMachine
+---------
+
+When using NoMachine, some users reported issues with rendering of the screen
+often with parts of the screen covered in green or black.
+
+Here is an example of how it can look like during an issue:
+
+.. figure:: /_static/nomachine_issue.png
+   :scale: 50 %
+   :alt: Example of NoMachine rendering issue
+
+
+To work around that follow the steps below:
+
+- Go to display > change settings.
+- Check all the 5 options on the bottom (See image below for reference).
+- Restart your entire session.
+- Now all your Qt-based screens should work properly.
+
+.. figure:: /_static/nomachine_settings.png
+   :scale: 50 %
+   :alt: Settings to be changed on NoMachine
diff --git a/v0.11.0/_static/_sphinx_javascript_frameworks_compat.js b/v0.11.0/_static/_sphinx_javascript_frameworks_compat.js
@@ -0,0 +1,123 @@
+/* Compatability shim for jQuery and underscores.js.
+ *
+ * Copyright Sphinx contributors
+ * Released under the two clause BSD licence
+ */
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+    if (!x) {
+        return x
+    }
+    return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+    if (typeof s === 'undefined')
+        s = document.location.search;
+    var parts = s.substr(s.indexOf('?') + 1).split('&');
+    var result = {};
+    for (var i = 0; i < parts.length; i++) {
+        var tmp = parts[i].split('=', 2);
+        var key = jQuery.urldecode(tmp[0]);
+        var value = jQuery.urldecode(tmp[1]);
+        if (key in result)
+            result[key].push(value);
+        else
+            result[key] = [value];
+    }
+    return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+    function highlight(node, addItems) {
+        if (node.nodeType === 3) {
+            var val = node.nodeValue;
+            var pos = val.toLowerCase().indexOf(text);
+            if (pos >= 0 &&
+                !jQuery(node.parentNode).hasClass(className) &&
+                !jQuery(node.parentNode).hasClass("nohighlight")) {
+                var span;
+                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+                if (isInSVG) {
+                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+                } else {
+                    span = document.createElement("span");
+                    span.className = className;
+                }
+                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+                    document.createTextNode(val.substr(pos + text.length)),
+                    node.nextSibling));
+                node.nodeValue = val.substr(0, pos);
+                if (isInSVG) {
+                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+                    var bbox = node.parentElement.getBBox();
+                    rect.x.baseVal.value = bbox.x;
+                    rect.y.baseVal.value = bbox.y;
+                    rect.width.baseVal.value = bbox.width;
+                    rect.height.baseVal.value = bbox.height;
+                    rect.setAttribute('class', className);
+                    addItems.push({
+                        "parent": node.parentNode,
+                        "target": rect});
+                }
+            }
+        }
+        else if (!jQuery(node).is("button, select, textarea")) {
+            jQuery.each(node.childNodes, function() {
+                highlight(this, addItems);
+            });
+        }
+    }
+    var addItems = [];
+    var result = this.each(function() {
+        highlight(this, addItems);
+    });
+    for (var i = 0; i < addItems.length; ++i) {
+        jQuery(addItems[i].parent).before(addItems[i].target);
+    }
+    return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+    jQuery.uaMatch = function(ua) {
+        ua = ua.toLowerCase();
+
+        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+            /(msie) ([\w.]+)/.exec(ua) ||
+            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+            [];
+
+        return {
+            browser: match[ 1 ] || "",
+            version: match[ 2 ] || "0"
+        };
+    };
+    jQuery.browser = {};
+    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}