Merge pull request slaclab#854 from klauer/doc_cleanup

DOC: fix miscellaneous docstring issues
prjemian · May 12, 2022 · 5740b1a · 5740b1a
2 parents 7945c24 + b031f8f
commit 5740b1a
Show file tree

Hide file tree

Showing 11 changed files with 127 additions and 59 deletions.
diff --git a/docs/source/data_plugins/calc_plugin.rst b/docs/source/data_plugins/calc_plugin.rst
@@ -14,17 +14,23 @@ General Calc Plugin channel syntax::
 
     calc://my_variable_name?expr_var_name=channel://address&expr_var_name_two=channel://address&expr=math expression
 
-.. note:: Once a calc channel is created, multiple widgets can be connected to the same channel by providing the name of the variable, like so:
-    ::
+.. note:: 
+
+   Once a calc channel is created, multiple widgets can be connected to the
+   same channel by providing the name of the variable, like so:
+
+   ::
 
         calc://my_variable_name
 
-.. note:: The calc functions uses url formatting. Where the name attribute is separated by the ? symbol and all other attributes are separated by the & symbol.
-    ::
+.. note:: 
 
--------------
+   The calc functions uses url formatting. Where the name attribute is
+   separated by the ? symbol and all other attributes are separated by the &
+   symbol.
 
 
+-------------------
 Required Attributes
 -------------------
 

diff --git a/docs/source/data_plugins/local_plugin.rst b/docs/source/data_plugins/local_plugin.rst
@@ -2,7 +2,7 @@
 Local Plugin
 ========================
 
-PyDM uses Data Plugins as sources of information to be displayed at the widgets. 
+PyDM uses Data Plugins as sources of information to be displayed at the widgets.
 Local Data Plugin allows users to create and use local variables.
 
 The Local Data Plugin stores the data that is sent by the widgets through a channel, and broadcasts it to all the listeners connected to this particular local variable channel.
@@ -39,7 +39,7 @@ Attributes  Description                                        Format Example
 =========== ================================================== ========================
 **loc**     protocol name for Local Data Plugin                `loc://`
 **name**    | the identifier for a local variable              `my_ndarray_var`
-            | user's choice 
+            | user's choice
 **type**    | data-type for this variable                      `type=array`
   	    | refer to :ref:`Variable Types<Variable Types>`
             | for more info of acceptable type
@@ -49,7 +49,7 @@ Attributes  Description                                        Format Example
 
 Here is a simple example of a channel address format with the required attributes:
 ::
-	
+
 	loc://my_np.array?type=array&init=[1,2,3,4]
 
 
@@ -58,20 +58,20 @@ Here is a simple example of a channel address format with the required attribute
 
 -------------
 
-.. _Extra Attributes:
+.. _Local Plugin Extra Attributes:
 
 Extra Attributes
 ----------------
 
 Along with the :ref:`required attributes<Required Attributes>`, the Local Data Plugin can also accept some optional attributes to configure the Local Variables with.
-The optional attributes are described in the :ref:`extra attributes<extra attributes table>` table below: 
+The optional attributes are described in the :ref:`extra attributes<extra attributes table>` table below:
 
 
 
-.. _extra attributes table: 
+.. _extra attributes table:
 
 The table below explains the optional attributes that can go in the *extras*:
-                                                             
+
 
 =============== =================================== ============ =================================
 Attributes      Description                         Type         Format Example
@@ -87,7 +87,7 @@ Attributes      Description                         Type         Format Example
 
 Here is a simple example of a channel address format with some optional attributes:
 ::
-	
+
 	loc://my.float?type=float&init=1&precision=3&unit=V
 
 -------------
@@ -130,7 +130,7 @@ Attributes      Description                         Type          Format Example
 **order**       memory layout of the array          string        | `order=K` (*default*)
                                                                   | others {'A', 'C', 'F'}
 **subok**       | if *True* then sub-classes        bool          `subok=false` (*default*)
-                | will be passed-through               
+                | will be passed-through
 **ndmin**       minimum number of dimensions        int           `ndmin=0` (*default*)
 =============== =================================== ============= =============================
 
@@ -155,11 +155,11 @@ The picture below represents a simple example using the Local Data Plugin, where
 
 Right below the Waveform Curve Editor widget, there are two other widgets connected to the 'x' and 'y' local variable respectively::
 
-	
+
 	X-values: loc://x
 	Y-values: loc://y
 
-Data can be updated in the two X and Y-values widgets and the Waveform Curve Editor will receive the new data and change the curve accordingly, like seen in the picture below: 
+Data can be updated in the two X and Y-values widgets and the Waveform Curve Editor will receive the new data and change the curve accordingly, like seen in the picture below:
 
 
 
@@ -176,7 +176,3 @@ Miscellaneous
 -------------
 
 * If precision is not set through the "extras", and it is set to receive the precision from the PV (Process Variable), the Local Data Plugin will match the precision from the values inserted by the users in the widgets.
-
-
-
-
diff --git a/docs/source/stylesheets.rst b/docs/source/stylesheets.rst
@@ -18,15 +18,14 @@ To help users extend this feature, PyDM offers two main configurations that can
 be used:
 
 - **PYDM_STYLESHEET**
-Path to the QSS files defining the global stylesheets for the PyDM application.
-When used, it will override the default look. If using multiple files they
-must be separated by the path separator.
-E.g.: ``/path_to/my_style_1.qss:/path_to/other/my_other_style.qss``
-
+  Path to the QSS files defining the global stylesheets for the PyDM
+  application. When used, it will override the default look. If using multiple
+  files they must be separated by the path separator.
+  For example: ``/path_to/my_style_1.qss:/path_to/other/my_other_style.qss``
 - **PYDM_STYLESHEET_INCLUDE_DEFAULT**
-Whether or not to include the PyDM Default stylesheet along with customized
-files. Note that the PyDM default stylesheet will have lower precedence compared
-to files specified at ``PYDM_STYLESHEET``
+  Whether or not to include the PyDM Default stylesheet along with customized
+  files. Note that the PyDM default stylesheet will have lower precedence
+  compared to files specified at ``PYDM_STYLESHEET``.
 
 Processing Order of Style Sheets
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/source/widgets/archiver_timeplot.rst b/docs/source/widgets/archiver_timeplot.rst
@@ -1,12 +1,13 @@
-#######################
+#####################################
 Archiver Appliance Enabled Time Plots
-#######################
+#####################################
 
 Time plots can be augmented with the ability to automatically request archived data from an instance
 of the EPICS archiver appliance if such an instance is available to the user.
 
 In order to use this functionality, the environment variable PYDM_ARCHIVER_URL must be set to point to
 the archiver appliance instance. For example:
+
 ::
     export PYDM_ARCHIVER_URL=http://lcls-archapp.slac.stanford.edu
 

diff --git a/docs/source/widgets/curve_editor.rst b/docs/source/widgets/curve_editor.rst
@@ -74,7 +74,8 @@ And for the axes tab:
   ``setAxes`` and  ``setCurves`` property to configure the plot properly.
 
 Bar Graphs
-++++
+++++++++++
+
 By selecting "Bar" from the style drop-down as described above, a curve can be plotted as a bar
 graph for waveform and time plots. This style of plot will have four additional options that may be set:
 

diff --git a/docs/source/widgets/index.rst b/docs/source/widgets/index.rst
@@ -61,3 +61,11 @@ Drawing Widgets
    :maxdepth: 1
 
    drawing.rst
+
+Utilities
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   utilities.rst
diff --git a/docs/source/widgets/utilities.rst b/docs/source/widgets/utilities.rst
@@ -0,0 +1,10 @@
+########################
+Display Format Utilities
+########################
+
+.. currentmodule:: pydm.widgets.display_format
+
+.. autoclass:: DisplayFormat
+   :members:
+
+.. autofunction:: parse_value_for_display
diff --git a/pydm/utilities/__init__.py b/pydm/utilities/__init__.py
@@ -177,13 +177,14 @@ def find_file(fname, base_path=None, mode=None, extra_path=None):
     """
     Look for files at the search paths common to PyDM.
 
-    Search Order
-    ------------
-    - base_path
-    - Qt Designer Path
-    - Current Dir
-    - Dirs in extra_path
-    - Dirs in PYDM_DISPLAYS_PATH
+    The search order is as follows:
+
+    * The ``base_path`` argument
+    * Qt Designer Path - the path for the current form as reported by the
+      designer
+    * The current working directory
+    * Directories listed in ``extra_path``
+    * Directories listed in the environment variable ``PYDM_DISPLAYS_PATH``
 
     Parameters
     ----------

diff --git a/pydm/widgets/archiver_time_plot.py b/pydm/widgets/archiver_time_plot.py
@@ -116,14 +116,17 @@ def receiveArchiveData(self, data: np.ndarray) -> None:
         self.archive_data_received_signal.emit()
 
     def insert_archive_data(self, data: np.ndarray) -> None:
-        """ Inserts data directly into the archive buffer. An example use case would be
-            zooming into optimized mean-value data and replacing it with the raw data
-
-             Parameters
-             ----------
-             data : np.ndarray
-                A numpy array of shape (2, length_of_data). Index 0 contains timestamps and index 1 contains
-                the data observations.
+        """
+        Inserts data directly into the archive buffer.
+
+        An example use case would be zooming into optimized mean-value data and
+        replacing it with the raw data.
+
+        Parameters
+        ----------
+        data : np.ndarray
+           A numpy array of shape (2, length_of_data). Index 0 contains
+           timestamps and index 1 contains the data observations.
         """
         archive_data_length = len(data[0])
         min_x = data[0][0]

diff --git a/pydm/widgets/baseplot.py b/pydm/widgets/baseplot.py
@@ -615,17 +615,21 @@ def eventFilter(self, obj, event):
 
     def addCurve(self, plot_data_item, curve_color=None, y_axis_name=None):
         """
-        Adds a curve to this plot. If the y axis parameters are specified, either link this curve to an existing
-        axis if that axis is already part of this plot, or create a new one and link the curve to it.
+        Adds a curve to this plot. 
+
+        If the y axis parameters are specified, either link this curve to an
+        existing axis if that axis is already part of this plot, or create a
+        new one and link the curve to it.
+
         Parameters
         ----------
         plot_data_item: BasePlotCurveItem
             The curve to add to this plot
         curve_color: QColor, optional
             The color to draw the curve and axis label in
         y_axis_name: str, optional
-            The name of the axis to link the curve with. If this is the first time seeing this name,
-            then a new axis will be created for it.
+            The name of the axis to link the curve with. If this is the first
+            time seeing this name, then a new axis will be created for it.
         """
 
         if curve_color is None:
@@ -657,7 +661,9 @@ def addAxis(self, plot_data_item: BasePlotCurveItem, name: str, orientation: str
                 label: Optional[str] = None, min_range: Optional[float] = -1.0,
                 max_range: Optional[float] = 1.0, enable_auto_range: Optional[bool] = True):
         """
-        Create an AxisItem with the input name and orientation, and add it to this plot.
+        Create an AxisItem with the input name and orientation, and add it to
+        this plot.
+
         Parameters
         ----------
         plot_data_item: BasePlotCurveItem
@@ -673,8 +679,9 @@ def addAxis(self, plot_data_item: BasePlotCurveItem, name: str, orientation: str
         max_range: float
             The maximum range to display on the axis
         enable_auto_range: bool
-            Whether or not to use autorange for this axis. Min and max range will not be respected
-            when data goes out of range if this is set to True
+            Whether or not to use autorange for this axis. Min and max range
+            will not be respected when data goes out of range if this is set to
+            True.
 
         Raises
         ------
@@ -841,10 +848,10 @@ def getShowRightAxis(self):
         """
         Provide whether the right y-axis is being shown.
 
-        Returns : bool
+        Returns
         -------
-        True if the graph shows the right y-axis. False if not.
-
+        bool
+            True if the graph shows the right y-axis. False if not.
         """
         return self._show_right_axis
 
@@ -933,8 +940,9 @@ def getShowLegend(self):
         """
         Check if the legend is being shown.
 
-        Returns : bool
+        Returns
         -------
+        bool
             True if the legend is displayed on the graph; False if not.
         """
         return self._show_legend

diff --git a/pydm/widgets/display_format.py b/pydm/widgets/display_format.py
@@ -1,5 +1,6 @@
 import math
 import numpy as np
+from typing import Any
 
 import logging
 import warnings
@@ -8,15 +9,49 @@
 
 
 class DisplayFormat(object):
+    """Display format for showing data in a PyDM widget."""
+    #: The default display format.
     Default = 0
+    #: Show the data as a string.
     String = 1
+    #: Show numerical values as floating point (base 10, decimal) values.
     Decimal = 2
+    #: Show numerical values in scientific / exponential notation.
     Exponential = 3
+    #: Show numerical values in base 16 (hexadecimal) notation.
     Hex = 4
+    #: Show numerical values in base 2 (binary) notation.
     Binary = 5
 
 
-def parse_value_for_display(value, precision, display_format_type=DisplayFormat.Default, string_encoding="utf_8", widget=None):
+def parse_value_for_display(
+    value: Any,
+    precision: int,
+    display_format_type: int = DisplayFormat.Default,
+    string_encoding: str = "utf_8",
+    widget=None,
+):
+    """
+    Format a value to show it in a widget, based on the display format type.
+
+    Parameters
+    ----------
+    value : Any
+        The value to convert to a string.
+    precision : int
+        Precision of floating point values to use.
+    display_format_type : int, optional
+        Display format type to use.
+    string_encoding : str, optional
+        Encoding to use for strings.
+    widget : QtWidgets.QWidget, optional
+        Widget to get a name from for conversion errors.
+
+    Returns
+    -------
+    str
+        Formatted version of ``value``.
+    """
     if value is None:
         return ""
     try:
@@ -37,7 +72,7 @@ def parse_value_for_display(value, precision, display_format_type=DisplayFormat.
                 if zeros.size > 0:
                     value = value[:zeros[0]]
                 r = value.tobytes().decode(string_encoding)
-            except:
+            except Exception:
                 logger.error("Could not decode {0} using {1} at widget named '{2}'.".format(
                     value, string_encoding, widget_name))
                 return value