DOC #333

.gitignore

@@ -20,3 +20,7 @@ build_log.txt
 .logs/
 .vscode/
 20*.dat
+
+# bird droppings from IT
+.log
+.loglogin

apstools/beamtime/apsbss.py

@@ -483,13 +483,13 @@ def get_options():
     p_sub = subcommand.add_parser('current', help="print current ESAF(s) and proposal(s)")
     p_sub.add_argument('beamlineName', type=str, help="Beamline name")
 
-    subcommand.add_parser('cycles', help="print APS cycle names")
+    subcommand.add_parser('cycles', help="print APS run cycle names")
 
     p_sub = subcommand.add_parser('esaf', help="print specific ESAF")
     p_sub.add_argument('esafId', type=int, help="ESAF ID number")
 
     p_sub = subcommand.add_parser('proposal', help="print specific proposal")
-    p_sub.add_argument('proposalId', type=str, help="ESAF ID number")
+    p_sub.add_argument('proposalId', type=str, help="proposal ID number")
     p_sub.add_argument('cycle', type=str, help="APS run (cycle) name")
     p_sub.add_argument('beamlineName', type=str, help="Beamline name")
 
@@ -627,6 +627,9 @@ def main():
     elif args.subcommand == "update":
         epicsUpdate(args.prefix)
 
+    else:
+        print("subcommand not recognized.  Use -h for usage information.")
+
 
 if __name__ == "__main__":
     main()

apstools/beamtime/manage_ioc.sh → apstools/beamtime/apsbss_ioc.sh

@@ -2,8 +2,11 @@
 
 # manage the IOC for apsbss
 
+#--------------------
+# change the program defaults here
 DEFAULT_SESSION_NAME=apsbss
 DEFAULT_IOC_PREFIX=ioc:bss:
+#--------------------
 
 SHELL_SCRIPT_NAME=${BASH_SOURCE:-${0}}
 SELECTION=${1:-usage}
@@ -120,10 +123,11 @@ function start() {
         echo -n "${SCREEN_SESSION} is already running (pid=${IOC_PID})"
         screenpid
     else
-        echo "Starting ${SESSION_NAME}"
+        echo "Starting ${SESSION_NAME} with IOC prefix ${IOC_PREFIX}"
         cd "${IOC_STARTUP_DIR}"
         # Run SESSION_NAME inside a screen session
-        screen -dm -S "${SESSION_NAME}" -h 5000 "${START_IOC_COMMAND}"
+        CMD="screen -dm -S ${SESSION_NAME} -h 5000 ${START_IOC_COMMAND}"
+        $CMD
     fi
 }
 

docs/source/applications/apsbss.rst

@@ -13,7 +13,8 @@ form) databases as PVs at each beam line so that this information
 (``dm`` for short) package [#]_
 is used to access the APS databases as read-only.
 
-*No information is written back to the APS databases.*
+*No information is written back to the APS
+databases from this software.*
 
 .. [#] ``dm``: https://anaconda.org/search?q=aps-dm-api
 
@@ -40,8 +41,8 @@ the typical information obtained includes:
 * is experiment mail-in?
 
 These PVs are loaded on demand by the local instrument team at the beam line.
-
-.. TODO: describe how this is done
+See the :ref:`apsbss_startup` section for details about
+managing the EPICS PVs.
 
 Example - command line
 ++++++++++++++++++++++
@@ -70,35 +71,22 @@ the *apsbss* application expects::
 		setup               EPICS PVs: setup
 		update              EPICS PVs: update from BSS
 
-.. TODO: describe each of these subcommands
-
-.. _apsbss_ioc_management:
+See :ref:`beamtime_source_docs` for the source code documentation
+of each of these subcommands.
 
 IOC Management
 ++++++++++++++
 
 The EPICS PVs are provided by running an instance of ``apsbss.db``
 either in an existing EPICS IOC or using the ``softIoc`` application
-from EPICS base.  A shell script (``manage_ioc.sh``) is included
-for management of the IOC::
-
-	$ ./manage_ioc.sh
-	Usage: manage_ioc.sh {start|stop|restart|status|console|run} [NAME [PREFIX]]
-
-		COMMANDS
-			console   attach to IOC console if IOC is running in screen
-			restart   restart IOC
-			run       run IOC in console (not screen)
-			start     start IOC
-			status    report if IOC is running
-			stop      stop IOC
+from EPICS base.  A shell script (``apsbss_ioc.sh``) is included
+for loading Proposal and ESAF information from the
+APS databases into the IOC.
 
-		OPTIONAL TERMS
-			NAME      name of IOC session (default: apsbss)
-			PREFIX    IOC prefix (default: ioc:bss:)
-
-.. TODO: download for ``apsbss.db``
+* :download:`apsbss.db <../../../apstools/beamtime/apsbss.db>`
 
+See the section titled ":ref:`apsbss_startup`"
+for the management of the EPICS IOC.
 
 .. _apsbss_epics_gui_screens:
 
@@ -108,9 +96,19 @@ Displays for MEDM & caQtDM
 Display screen files are provided for viewing the EPICS PVs
 using either MEDM (``apsbss.adl``) or caQtDM (``apsbss.ui``).
 
-.. TODO: downloads for each screen file
+* MEDM screen: :download:`apsbss.adl <../../../apstools/beamtime/apsbss.adl>`
+* caQtDM screen: :download:`apsbss.ui <../../../apstools/beamtime/apsbss.ui>`
+
 .. TODO: screen images here
 
+Downloads
++++++++++
+
+* EPICS database: :download:`apsbss.db <../../../apstools/beamtime/apsbss.db>`
+* EPICS IOC shell script :download:`apsbss_ioc.sh <../../../apstools/beamtime/apsbss_ioc.sh>`
+* MEDM screen: :download:`apsbss.adl <../../../apstools/beamtime/apsbss.adl>`
+* caQtDM screen: :download:`apsbss.ui <../../../apstools/beamtime/apsbss.ui>`
+
 Source code documentation
 +++++++++++++++++++++++++