Merge pull request #1032 from nstelter-slac/tutorial_ioc

ENH: Add new PCASpy server for running the tutorial.

README.md

@@ -9,8 +9,7 @@
     as well as a straightforward Python framework to build complex applications.
     <br>
     <br>
-    <strong>« Explore PyDM <a href="https://slaclab.github.io/pydm/">docs</a> and <a href="https://slaclab.github.io/pydm-tutorial">tutorials</a> »</strong>
-    <br>
+    <strong>« Explore PyDM <a href="https://slaclab.github.io/pydm/">docs</a> and <a href="https://slaclab.github.io/pydm/tutorials/index.html">tutorials</a> »</strong>
     <br>
     <a href="https://github.com/slaclab/pydm/issues/new?template=bug-report.md">Report bug</a>
     ·

docs/source/conf.py

@@ -56,8 +56,8 @@
 
 # General information about the project.
 project = "PyDM"
-copyright = "2016, mgibbs, hhslepicka, trendahl, zlentz"
-author = "mgibbs, hhslepicka, trendahl, zlentz"
+copyright = "2023, hhslepicka, trendahl, zlentz, yektay, nstelter"
+author = "mgibbs, hhslepicka, trendahl, zlentz, yektay, nstelter"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -73,7 +73,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

docs/source/installation.rst

@@ -1,3 +1,5 @@
+.. _Install:
+
 =========================
 Installation
 =========================

docs/source/tutorials/action/designer_expert.rst

@@ -5,13 +5,7 @@ Expert Motor Screen
 
 .. important::
 
-    **Check-list:**
-
-    * Make sure that you have your :ref:`Environment <Environment>` properly configured.
-    * That your :ref:`VirtualMachine` is up and ready.
-    * That the :ref:`Python environment <PythonEnv>` is set.
-    * That all :ref:`three IOCs <IOCS>` are running.
-
+    * Make sure the PCASpy tutorial server is :ref:`running <Setup>`
 
 For this screen we will present detailed information to the user for the motors.
 Also, to ensure that we can re-use this screen in other displays, it will be
@@ -312,4 +306,4 @@ The finished result will look like this:
      :alt: Expert Motor Screen
 
 .. note::
-    You can download this file using :download:`this link </_static/code/expert_motor.ui>`.
+    You can download this file using :download:`this link <../../../../examples/tutorial/expert_motor.ui>`.

docs/source/tutorials/action/designer_inline.rst

@@ -5,12 +5,7 @@ Inline Motor Screen
 
 .. important::
 
-    **Check-list:**
-
-    * Make sure that you have your :ref:`Environment <Environment>` properly configured.
-    * That your :ref:`VirtualMachine` is up and ready.
-    * That the :ref:`Python environment <PythonEnv>` is set.
-    * That all :ref:`three IOCs <IOCS>` are running.
+    * Make sure the PCASpy tutorial server is :ref:`running <Setup>`
 
 For this screen, we want to present useful information to the user to operate
 the motors, and also provide a way for them to access other less-commonly-used parameters via an "Expert" screen. To make this screen re-usable in other displays, it will be necessary
@@ -284,4 +279,4 @@ The finished result will look like this:
      :alt: Inline Motor Screen
 
 .. note::
-    You can download this file using :download:`this link </_static/code/inline_motor.ui>`.
+    You can download this file using :download:`this link <../../../../examples/tutorial/inline_motor.ui>`.

docs/source/tutorials/action/designer_main.rst

@@ -5,13 +5,7 @@ Main Screen
 
 .. important::
 
-    **Check-list:**
-
-    * Make sure that you have your :ref:`Environment <Environment>` properly configured.
-    * That your :ref:`VirtualMachine` is up and ready.
-    * That the :ref:`Python environment <PythonEnv>` is set.
-    * That all :ref:`three IOCs <IOCS>` are running.
-
+    * Make sure the PCASpy tutorial server is :ref:`running <Setup>`
 
 This will be the main piece of our Beam Positioning application and will group the other
 components of this tutorial.
@@ -256,5 +250,10 @@ The finished result will look like this:
      :alt: Main Application Screen
 
 .. note::
-    You can download this file using :download:`this link </_static/code/main.ui>`.
+    Purple borders will appear around any widgets that have "Alarm Sensitive Border" enabled.
+    These can be removed by simply unchecking the setting. (for the purposes of this tutorial,
+    these borders are not significant and can be in either the on or off state)
+
+.. note::
+    You can download this file using :download:`this link <../../../../examples/tutorial/main.ui>`.
 

docs/source/tutorials/action/little_code.rst

@@ -5,12 +5,7 @@ Adding Code into the Main Display
 
 .. important::
 
-    **Check-list:**
-
-    * Make sure that you have your :ref:`Environment <Environment>` properly configured.
-    * That your :ref:`VirtualMachine` is up and ready.
-    * That the :ref:`Python environment <PythonEnv>` is set.
-    * That all :ref:`three IOCs <IOCS>` are running.
+    * Make sure the PCASpy tutorial server is :ref:`running <Setup>`
 
 For this particular application it would be of interest to not only see the beam
 image on the screen, but to also calculate the maximum point on the image and display
@@ -145,4 +140,4 @@ This is accomplished by subclassing `pydm.Display` (See :ref:`Display` for more
      :align: center
 
 .. note::
-    You can download this file using :download:`this link </_static/code/main.py>`.
+    You can download this file using :download:`this link </_static/tutorials/code/main.py>`.

docs/source/tutorials/action/python.rst

@@ -5,12 +5,7 @@ Making Pure Python Displays
 
 .. important::
 
-    **Check-list:**
-
-    * Make sure that you have your :ref:`Environment <Environment>` properly configured.
-    * That your :ref:`VirtualMachine` is up and ready.
-    * That the :ref:`Python environment <PythonEnv>` is set.
-    * That all :ref:`three IOCs <IOCS>` are running.
+    * Make sure the PCASpy tutorial server is :ref:`running <Setup>`
 
 As we saw in the :ref:`A Word About Python Display <Python>` section, it is
 possible to make displays using Python code and a .ui file from Qt Designer.
@@ -37,7 +32,7 @@ Here is how it will look once we are done:
 
    In order to simplify this tutorial, instead of using a database or other type
    of service, the data to populate the list of motors will come from a simple text file
-   named ``motor_db.txt`` that can be downloaded :download:`here </_static/code/motor_db.txt>`.
+   named ``motor_db.txt`` that can be downloaded :download:`here </_static/tutorials/code/motor_db.txt>`.
 
 * **Step 1.**
 
@@ -259,4 +254,4 @@ Here is how it will look once we are done:
      :align: center
 
 .. note::
-    You can download this file using :download:`this link </_static/code/all_motors.py>`.
+    You can download this file using :download:`this link </_static/tutorials/code/all_motors.py>`.

docs/source/tutorials/contrib/requests.rst

@@ -6,7 +6,7 @@ Follow the steps below to increase the chances of a quick resolution.
 
 1. Is it a problem, a question or a request?
 --------------------------------------------
-For questions about how to use PyDM, please refer to the :doc:`/contrib/help` page.
+For questions about how to use PyDM, please refer to the :doc:`help` page.
 
 If you don't have a GitHub account we strongly encourage you to create one by following the 3 easy steps described on this `page <https://github.com/join>`_.
 
@@ -18,10 +18,10 @@ Problems (not questions!) with the software or website can be reported as GitHub
 - Typos or other mistakes in the Reference or elsewhere on the documentation
 
 If you create a new issue that’s really just a clarifying question about how to use PyDM, we’ll close it and nicely ask
-you to visit the :doc:`/contrib/help` channels in the future.
+you to visit the :doc:`help` channels in the future.
 
 Ideas or suggestions for enhancements should be posted as GitHub issues with the 'REQUEST: ' prefix to your issue title.
-When in doubt, start by reaching us through one of the :doc:`/contrib/help` channels.
+When in doubt, start by reaching us through one of the :doc:`help` channels.
 
 
 2. Write helpfully

docs/source/tutorials/intro.rst

@@ -1,94 +1,42 @@
-.. _Environment:
+.. _Setup:
 
-Setting up the Environment
+Tutorial Setup
 ==========================
 
-.. _VirtualMachine:
-
-Virtual Machine
+PCASpy Server
 ---------------
 
-We provide a virtual machine disk that is the base for the application that will
-be developed during this tutorial.
-
-You can download the disk using this `Link <https://drive.google.com/a/stanford.edu/file/d/1SE4_oDF2wg_7ltKOIdJuZIqkpHzLUkbm/view?usp=sharing>`_.
-
-Using the Downloaded Disk
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-After downloading it, extract the ``.tar.gz`` file, create a new Virtual Machine at the virtualization client of your preference.
-
-The instructions below are for `Oracle VirtualBox <https://www.virtualbox.org/wiki/Downloads>`_ .
-Oracle VirtualBox is available for Windows, OS X and Linux hosts.
-
-This file is not a complete Virtual Machine dump that can be imported but instead a disk.
-
-In order to use this disk, start by creating a new virtual Machine, select Type as ``Linux`` and Version as ``Ubuntu (64-bit)``.
-Configure the amount of memory to use (something greater or equal 2048MB should do it.
-Make sure to select ``Use an existing virtual hard disk file.`` and select the extracted ``.vmdk`` file.
-
-.. figure:: /_static/tutorials/new_vm.png
-    :scale: 100 %
-    :align: center
-    :alt: Create new VM
-
+A `PCASpy <https://pcaspy.readthedocs.io/en/latest/>`_ server provides PVs for the tutorial files to read/write.
 
-Useful Virtual Machine Information
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The server mimics some PVs of a motor and camera, and is located as follows:
+ .. code-block:: bash
 
-User Account
-++++++++++++
-========    ========
-Username    Password
-========    ========
-user        tutorial
-========    ========
+    examples/testing_ioc/pydm-tutorial-ioc
 
-.. _PythonEnv:
+Installing PCASpy from the documentation above and following the :ref:`pydm installation instructions<Install>` provides all needed prerequisites for this tutorial.
 
-Python Environment
-++++++++++++++++++
-
-On this machine we are using Miniconda to handle our Python environment and dependencies.
-To have access to the environmnet please do:
-
-.. code-block:: bash
-
-    source activate tutorial
-
-.. _IOCS:
-
-Simulated EPICS IOCs
-++++++++++++++++++++
-
-This machine comes with simulated motors and cameras.
-The IOCs can be started through their launcher scripts available at:
-
-.. code-block:: bash
-
-    cd ~/tutorial/iocs_launcher
-
-    # For the AreaDetector (cameras) simulation use
-    ./simDetector
+Using the PCASpy Server
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    # For the simulated motor axis use
-    ./simMotor
+.. note::
+    You will need to export the following variable in each terminal that will run either the PCASpy server or pydm:
+     .. code-block:: bash
 
-    # For the linking IOC
-    ./simLinker
+       export EPICS_CA_MAX_ARRAY_BYTES=300000
 
-For AreaDetector (cameras):
+Run the server as follows:
+ .. code-block:: bash
 
--  The prefix for the PVs is ``13SIM1:`` so we have: ``13SIM1:cam1`` as well as ``13SIM1:cam2`` available.
+    ./examples/testing_ioc/pydm-tutorial-ioc
 
-For Motor Axis:
+In another terminal window, enable the sever's running state:
+ .. code-block:: bash
 
-- The prexif for the PVs is ``IOC:`` so we have: ``IOC:m1 .. IOC:m8``
+    caput IOC:Run 1
 
+The server will now be running and the tutorial files can access the necessary PV's.
 
-Creating your own environment
------------------------------
+In another (third) terminal window, the completed tutorial files can be ran as follows:
+ .. code-block:: bash
 
-If you decide to create your own environment and not use the Virtual Machine
-provided please refer to the `PyDM Documentation Website <http://slaclab.github.io/pydm/>`_
-for an up-to-date dependency list as well as detailed installation instructions.
+    pydm <tutorial_file_name>.ui|.py

docs/source/utilities/index.rst

@@ -10,9 +10,6 @@ General
 .. automodule:: pydm.utilities
    :members:
 
-.. automodule:: pydm.utilities.remove_protocol
-   :members:
-
 --------
 Icons
 --------

docs/source/widgets/analog_indicator.rst

@@ -25,6 +25,7 @@ backgroundSizeRate = 0.4.
     :align: center
 
 * Suggested Orientations
+
 Horizontal with value displayed on the right.
 Vertical with value displayed on bottom.
 
@@ -39,6 +40,7 @@ There are a few methods of not drawing alarm regions.
   1. Set the alarm to the corresponding limit. Do not set the alarm to outside of the limits, this will cause drawing errors.
   2. Set userUpperMajorAlarm = userLowerMajorAlarm = 0.  Or set userUpperMinorAlarm = userLowerMinorAlarm = 0.
   3. If any alarm value is set to nan (not a number), those regions won't draw.  Setting an alarm value to nan is not possible in designer.
+
 .. figure:: /_static/widgets/analog_indicator/no_upper_minor.png
     :scale: 100%
     :align: center

docs/source/widgets/archiver_timeplot.rst

@@ -46,7 +46,7 @@ be plotted as bars to show the full range of data represented by each point. As
 of 365, a request for a year of data for a PV that updates every second would return roughly
 365 points each of which will contain the min and max of that day's data to plot the full range represented.
 
-.. figure:: /_static/widgets/archiver_time_plot/archiver_time_plot.gif
+.. figure:: /_static/widgets/archiver_time_plot/archiver_plot.gif
    :scale: 100 %
    :align: center
    :alt: Requesting additional data from a live plot

docs/source/widgets/index.rst

@@ -17,6 +17,8 @@ Display Widgets
    related_display_button.rst
    scale.rst
    symbol.rst
+   analog_indicator.rst
+   nt_table.rst
 
 Input Widgets
 -------------
@@ -62,6 +64,13 @@ Drawing Widgets
 
    drawing.rst
 
+Base Widgets
+------------
+.. toctree::
+   :maxdepth: 1
+
+   PyDMWidget.rst
+
 Utilities
 ---------