DOC overhaul

CHANGES.rst

@@ -27,6 +27,7 @@ History of user-visible changes between the versions.
    ----------------
 
    * Documentation moved to GitHub Pages (from readthedocs).
+   * Documentation now uses 'pydata_sphinx_theme'.
    * Project moved to GitHub "BCDA-APS" organization.
    * Python 3.8 - 3.12 now supported (no Python 2 support).
    * Switch to use PyDM widgets (dropped bcdaqwidgets).

README.md

@@ -7,9 +7,8 @@ tag | release | PyPI | conda
 --- | --- | --- | ---
 [![image](https://img.shields.io/github/tag/prjemian/PvMail.svg)](https://github.com/prjemian/PvMail/tags) |  [![image](https://img.shields.io/github/release/prjemian/PvMail.svg)](https://github.com/prjemian/PvMail/releases) | [![image](https://img.shields.io/pypi/v/PvMail.svg)](https://pypi.python.org/pypi/PvMail/) | --tba--
 
-- docs:   <https://PvMail.readthedocs.io>
-- git:   <https://github.com/prjemian/pvMail>
-- author:   Pete R. Jemian
-- email:   <[email protected]>
 - copyright:   (c) 2009-2024, UChicago Argonne, LLC
-- license:   ANL OPEN SOURCE LICENSE (see *LICENSE*)
+- license: [ANL OPEN SOURCE LICENSE](./src/PvMail/LICENSE)
+- documentation: [https://prjemian.github.io/pvMail/](https://prjemian.github.io/pvMail/)
+- source: [https://github.com/prjemian/pvMail](https://github.com/prjemian/pvMail)
+- authors: Pete R. Jemian, Kurt Goetze

docs/source/command_line.rst

@@ -1,4 +1,3 @@
-
 .. _cli:
 
 pvMail: command-line interface
@@ -19,21 +18,21 @@ GUI::
 
 	pvMail triggerPV messagePV [email protected],[email protected] -g &
 
-PvMail uses Matt Newville's `PyEpics <http://cars9.uchicago.edu/software/python/pyepics3/>`_ 
-package for EPICS CA connections and `PyQt4 <http://pypi.python.org/pypi>`_ 
-package to manage the GUI.
-
 .. tip::
    Since *PvMail* creates a log file (by default in the current working directory),
    be sure you start the program from a directory to which you have write
    access or specify the absolute path to the log file as a command line
    argument::
-   
+
      pvMail -l /path/to/log_file.txt triggerPV messagePV [email protected] &
 
 
+Starting PvMail
++++++++++++++++
+
+
 Starting PvMail from the command-line
-+++++++++++++++++++++++++++++++++++++
+-------------------------------------
 
 .. index:: example
 
@@ -45,7 +44,7 @@ PvMail is started from the command line::
 
 No program output is printed to the screen.  Instead, the output is directed
 to a log file.  Here is an example::
-   
+
 	INFO:root:(pvMail.py,2011-11-27 19:03:23.072392) ############################################################
 	INFO:root:(pvMail.py,2011-11-27 19:03:23.072826) startup
 	INFO:root:(pvMail.py,2011-11-27 19:03:23.072897) trigger PV       = pvMail:trigger
@@ -75,18 +74,18 @@ to a log file.  Here is an example::
 The program starts, reports its configurations, and connects with the
 EPICS PVs, and then goes into a background mode.  A checkpoint (command-line
 option ``-i``) is reported periodically.  The default is 5 seconds.  This may
-be changed to 10 minutes or longer for production use, but is always 
+be changed to 10 minutes or longer for production use, but is always
 specified in seconds.
 
-Observe that, in the above example, the trigger PV changed from 0 to 1 at 
-19:03:27.373142 (and back to 0 at 19:03:29.440516).  
+Observe that, in the above example, the trigger PV changed from 0 to 1 at
+19:03:27.373142 (and back to 0 at 19:03:29.440516).
 The change at ~19:03:27 triggered PvMail to send an email as configured.
 For now, the code writes the text of the email to a temporary file
 (command-line option ``-m``, default is "/tmp/pvmail_message.txt").
 In this example, the message reads::
 
 	pvMail default message
-	
+
 	user: jemian
 	host: como-ubuntu64
 	date: 2011-11-27 19:03:27.374135
@@ -117,9 +116,9 @@ The full message, as seen in the mail browser is::
 	Subject: pvMail.py: pvMail:trigger
 	From: Pete R Jemian <jemian@como-ubuntu64>
 	Date: Sun, 27 Nov 2011 19:03:27 -0600
-	
+
 	pvMail default message
-	
+
 	user: jemian
 	host: como-ubuntu64
 	date: 2011-11-27 19:03:27.374135
@@ -130,7 +129,7 @@ The full message, as seen in the mail browser is::
 	recipients: jemian
 
 Starting PvMail from the command-line at the APS
-++++++++++++++++++++++++++++++++++++++++++++++++
+------------------------------------------------
 
 At the APS, Enthought Python Distribution is installed on the /APSshare partition
 available to all beam lines.
@@ -151,65 +150,65 @@ or the 32-bit version::
 
 
 command-line parameters
-=======================
++++++++++++++++++++++++
 
 .. index:: command-line
 
 .. index:: usage
 
 usage
-+++++
+-----
 
 .. index:: example
 
 When PvMail is started from the command line with no additional parameters::
 
 	$ pvMail
-	
+
 	usage: pvMail [-h] [-l LOG_FILE] [-i LOGGING_INTERVAL]
 	                 [-r SLEEP_DURATION] [-g] [-v]
 	                 trigger_PV message_PV email_addresses
 	pvMail: error: too few arguments
 
 This is the *usage* message.
-It tells us we must supply three :index:`positional arguments`: 
+It tells us we must supply three :index:`positional arguments`:
 ``trigger_PV message_PV email_addresses``.
 
 positional argument: ``trigger_PV``
-+++++++++++++++++++++++++++++++++++
+-------------------------------------
 
-EPICS process variable name to watch using a CA monitor.  
+EPICS process variable name to watch using a CA monitor.
 When ``trigger_PV`` makes a transition from 0 (zero) to 1 (one),
 then get the string from the ``message_PV`` and send an email
 to all of the ``email_addresses`` on the list.
 
 positional argument: ``message_PV``
-+++++++++++++++++++++++++++++++++++
+-------------------------------------
 
 EPICS process variable name pointing to a (short) message that will
 be used as the first part of the email message to be sent.
 
 .. Can this be a waveform of char acting as a string?  Probably but test it.
 
 positional argument: ``email_addresses``
-++++++++++++++++++++++++++++++++++++++++
+----------------------------------------
 
 List of email addresses, separated by commas if more than one.  For example,
-``[email protected],[email protected]`` will send one email to 
+``[email protected],[email protected]`` will send one email to
 ``[email protected]`` and another email to ``[email protected]``.
 
 .. index:: email to a pager at APS
 
 ..	note::
 	At Argonne, it is possible to send email to a pager using
 	the email address ``####@pager.anl.gov`` and the pager number.
-	Be sure not to use a preceding ``4-`` or the email will not be 
+	Be sure not to use a preceding ``4-`` or the email will not be
 	deliverable.
 
 .. index:: optional arguments
 
 option: ``--version``  or  ``-v``
-+++++++++++++++++++++++++++++++++
+-----------------------------------
 
 The current version of the program can always be printed using the
 ``-v`` or ``--version``.  With this option, the program prints
@@ -221,22 +220,22 @@ the version number and then quits.
 	3.0-663
 
 option: ``--help``  or  ``-h``
-++++++++++++++++++++++++++++++
+-----------------------------------
 
 It may be easier to review the short help instructions for command-line options::
 
 	$ ./pvMail --help
 	usage: pvMail [-h] [-l LOG_FILE] [-i LOGGING_INTERVAL]
 	                 [-r SLEEP_DURATION] [-g] [-v]
 	                 trigger_PV message_PV email_addresses
-	
+
 	Watch an EPICS PV. Send email when it changes from 0 to 1.
-	
+
 	positional arguments:
 	  trigger_PV           EPICS trigger PV name
 	  message_PV           EPICS message PV name
 	  email_addresses      email address(es), comma-separated if more than one
-	
+
 	optional arguments:
 	  -h, --help           show this help message and exit
 	  -l LOG_FILE          for logging program progress and comments
@@ -246,51 +245,51 @@ It may be easier to review the short help instructions for command-line options:
 	  -v, --version        show program's version number and exit
 
 option: ``--gui``  or ``-g``
-++++++++++++++++++++++++++++
+-----------------------------------
 
 This command line option is used to start the GUI (see :ref:`GUI`).
-If either GUI option is used, then the positional arguments 
+If either GUI option is used, then the positional arguments
 (``triggerPV messagePV email@address``) are optional.
 
 option: ``-l LOG_FILE``
-+++++++++++++++++++++++
+-----------------------------------
 
 Both the command-line and GUI versions of PvMail log all
 program output to a log file.  If a LOG_FILE is not specified on the command
-line, the default file will be ``pvMail-PID.log`` in the current directory 
+line, the default file will be ``pvMail-PID.log`` in the current directory
 where *PID* is the process identifier of the running ``pvMail`` program.
 
 ..	note::
 	If the LOG_FILE already exists, new information will be appended.
-	It is up to the account owner to delete a LOG_FILE when it is no 
+	It is up to the account owner to delete a LOG_FILE when it is no
 	longer useful.
 
-The PID number is useful when you wish to end a program that is running 
+The PID number is useful when you wish to end a program that is running
 as a background daemon.  The UNIX/Linux command is::
 
 	kill PID
 
 option: ``-i LOGGING_INTERVAL``
-+++++++++++++++++++++++++++++++
+-----------------------------------
 
 :units: seconds
 
 When a program runs in the background, waiting for occasional activity,
 there is often some concern that the program is actually prepared to act
-when needed.  To offset this concern, PvMail will report a 
+when needed.  To offset this concern, PvMail will report a
 *checkpoint* message periodically (every LOGGING_INTERVAL seconds,
 default is every 5 minutes) to the LOG_FILE.  The program ensures that
 LOGGING_INTERVAL is no shorter than 5 seconds or longer than 1 hour.
 
 option: ``-r SLEEP_DURATION``
-+++++++++++++++++++++++++++++
+-----------------------------------
 
 :units: seconds
 
 For operation as a background daemon process, the command-line version
-must check periodically for new EPICS CA events, using a call to 
+must check periodically for new EPICS CA events, using a call to
 :meth:`epics.ca.poll()`.  In between calls, the application is told to sleep
-for SLEEP_DURATION seconds.  The default SLEEP_DURATION is 0.2 seconds and 
-is limited to values between 0.1 ms and 5 s. 
+for SLEEP_DURATION seconds.  The default SLEEP_DURATION is 0.2 seconds and
+is limited to values between 0.1 ms and 5 s.
 
 

docs/source/contents.rst

@@ -9,8 +9,8 @@ Contents
    command_line
    gui
    test_database
-   pvMail/modules
    info
+   pvMail/index
    changes
    license
 

docs/source/glossary.rst

@@ -1,3 +1,4 @@
+.. _glossary:
 
 Glossary
 ========
@@ -27,6 +28,9 @@ Glossary
 :index:`PV`
     EPICS process variable
 
+:index:`PVA`
+    EPICS PV Access protocol (not used here)
+
 :index:`PvMail`
     Name of the Python package that provides the ``pvMail`` executable
 
@@ -36,7 +40,7 @@ Glossary
 :index:`PyEpics`
     Python package to manage connections with PVs served by an EPICS IOC
 
-:index:`PyQt4`
+:index:`PyQt5`
     Python framework for GUI and other Qt components
 
 :index:`trigger PV`