documentation updates

doc/source/lvalert.rst

@@ -6,7 +6,7 @@ Introduction
 ===============================================
 
 GraceDB uses `LVAlert
-<https://www.lsc-group.phys.uwm.edu/daswg/projects/lvalert.html>`__ to send
+<https://wiki.ligo.org/DASWG/LVAlert>`__ to send
 alerts to listeners within the LVC.  The content of the LVAlert message is
 designed to convey actionable information about a state change in GraceDB,
 whether it involves the creation of a new event, or the updating or labeling of
@@ -41,7 +41,7 @@ specifying different LVAlert processing scripts for different nodes.
 
 To see the names of all available nodes, simply execute::
 
-    lvalert_admin -a username -b password -i
+    lvalert_admin -a username -i
 
 LVAlert message contents
 ================================================
@@ -203,7 +203,7 @@ Receiving and Parsing LVAlert messages
 The LVAlert client tools include the ``lvalert_listen`` executable, which can be used to
 receive and respond to LVAlert messages::
 
-    lvalert_listen -a username -b password -c /path/to/lvalert_config.ini
+    lvalert_listen -a username -c /path/to/lvalert_config.ini
 
 The ``-c`` (configuration file) option allows you to specify an executable script to be called 
 each time a message arrives over a particular node. Suppose you are only interested in
@@ -238,5 +238,5 @@ Further reading on LVAlert
 =====================================================
 
 Further information on using LVAlert can be found on the
-`LVAlert Project Page <https://www.lsc-group.phys.uwm.edu/daswg/projects/lvalert.html>`__
-and the `LVAlert Howto <https://www.lsc-group.phys.uwm.edu/daswg/docs/howto/lvalert-howto.html>`__.
+`LVAlert Project Page <https://wiki.ligo.org/DASWG/LVAlert>`__
+and the `LVAlert Howto <https://wiki.ligo.org/DASWG/LVAlertHowto>`__.

doc/source/lvem.rst

@@ -165,7 +165,7 @@ observation records:
   consider sending us your script or posting it in the LV-EM wiki Technical Info
   page for the benefit of other users. See :ref:`coding_against_api`.  
 
-- by email (not yet availabe, but in the works)
+- by email (not yet available, but in the works)
 
 If you discover a mistake in your observation record, the best way to correct
 it is to submit a new observation record with corrected values and request that
@@ -174,7 +174,7 @@ something like "delete GraceDB EMObservation" in the subject line. Tell us
 which entry you'd like deleted, and we'll take care of it.  In the future, we
 are hoping to make these observation records editable by the submitter.
 
-For more on the GraceBD event page and creating EM observation records, see 
+For more on the GraceDB event page and creating EM observation records, see 
 `this <https://www.youtube.com/watch?v=oIJE4dTISs4>`__  helpful video
 by Roy Williams.  There is a companion video on the SkymapViewer 
 `here <https://www.youtube.com/watch?v=ydXUD9KIN98>`__.

doc/source/models.rst

@@ -12,7 +12,7 @@ The different types of events in GraceDB are distinguished by the following para
 - ``Pipeline``: the data analysis software tool used make the detection 
     - values: ``MBTAOnline``, ``CWB``, ``gstlal``, ``gstlal-spiir``, ``HardwareInjection``, ``Fermi``, ``Swift``, ``SNEWS``, ``LIB``
 - ``Search``: the search activity which led to the detection 
-    - values: ``AllSky``, ``LowMass``, ``HighMass``, ``GRB``, ``Supernova``, ``MDC``
+    - values: ``AllSky``, ``AllSkyLong``, ``LowMass``, ``HighMass``, ``GRB``, ``Supernova``, ``MDC``
 
 An individual "event stream" is specified by setting the values of these three 
 parameters.  For example, choosing ``Group=CBC, Pipeline=gstlal, and Search=LowMass`` 

doc/source/responding_to_lvalert.rst

@@ -53,36 +53,44 @@ those events in GraceDB.
 
 Fill out the form and follow all instructions to create an account attached to
 your "user.name". For the rest of this tutorial, I will refer to the username
-as "user.name" and the password as "passw0rd", but you should replace these
-with your own account's information.
+as "user.name", but you should replace this with your own account's information.
+You'll be prompted for your password after each command.
+
+*Note: To bypass this, create a .netrc file in your home directory and enter your
+authentication information*::
+
+    machine lvalert.cgca.uwm.edu login user.name password passw0rd
+
+*With this setup, you won't need to include the* ``-a`` *flag for your username, 
+or enter your password.*
 
 To actually subscribe to a pubsub node, we use ``lvalert_admin``
 which allows you to manage your subscriptions. This includes subscribing to new
 nodes, unsubscribing from nodes and viewing your current subscriptions. We will
 now subscribe your account to ``cbc_gstlal_lowmass``. Run::
 
-    lvalert_admin -a user.name -b passw0rd --subscribe --node cbc_gstlal_lowmass
+    lvalert_admin -a user.name --subscribe --node cbc_gstlal_lowmass
 
 You can confirm that your account is successfully subscribed to this node by
 running::
 
-    lvalert_admin -a user.name -b passw0rd --subscriptions
+    lvalert_admin -a user.name --subscriptions
 
 which will list your account's subscriptions. You should see
 ``cbc_gstlal_lowmass`` in the resulting list.  To unsubscribe from a node, use::
 
-    lvalert_admin -a user.name -b passw0rd --unsubscribe --node cbc_gstlal_lowmass
+    lvalert_admin -a user.name --unsubscribe --node cbc_gstlal_lowmass
 
 but for now we'll leave our subscription in place. If you'd like to subscribe
 to other nodes, simply repeat the subscription command and replace
 ``cbc_gstlal_lowmass`` with the name of the node to which you'd like to
 subscribe. A complete list of nodes is available by running::
 
-    lvalert_admin -a user.name -b passw0rd --get-nodes
+    lvalert_admin -a user.name --get-nodes
 
 For this tutorial, let's subscribe to another node to show how things scale.  Run::
 
-    lvalert_admin -a user.name -b passw0rd --subscribe --node cbc_gstlal_highmass
+    lvalert_admin -a user.name --subscribe --node cbc_gstlal_highmass
 
 Creating an LVAlert node
 ========================
@@ -90,23 +98,23 @@ Creating an LVAlert node
 Users can create their own LVAlert pubsub nodes as well. Unsurprisingly, this
 is also straightforward. Simply run::
 
-    lvalert_admin -a user.name -b passw0rd --create --node user.name-TestNode
+    lvalert_admin -a user.name --create --node user.name-TestNode
 
 to create a node called ``user.name-TestNode``. Of course, you'll want to change
 "user.name" to your account's name. Go ahead and create this node. If you need
 to delete it at any time, you can with::
 
-    lvalert_admin -a user.name -b passw0rd --delete --node user.name-TestNode
+    lvalert_admin -a user.name --delete --node user.name-TestNode
 
 but leave it be for the moment. You now have a node owned by your account to
 which you can publish alerts. We'll come back to this when we test our set-up.
 You will also need to subscribe to this node with::
 
-    lvalert_admin -a user.name -b passw0rd --subscribe --node user.name-TestNode
+    lvalert_admin -a user.name --subscribe --node user.name-TestNode
 
 Run::
 
-    lvalert_admin -a user.name -b passw0rd --subscriptions
+    lvalert_admin -a user.name --subscriptions
 
 and make sure you see::
 
@@ -136,14 +144,14 @@ create a file called ``myLVAlertListen.ini`` with the following as its contents:
 
 Now run::
 
-    lvalert_listen -a user.name -b passw0rd -c myLVAlertListen.ini > myLVAlertListen.out &
+    lvalert_listen -a user.name  -c myLVAlertListen.ini > myLVAlertListen.out &
 
 Congratulations! You've set up an ``lvalert_listen`` instance which reacts to
 announcements published to the ``cbc_gstlal_lowmass``, ``cbc_gstlal_highmass`` and
 ``user.name-TestNode`` nodes.
 
 Here's what's happening: ``lvalert_listen`` hears announcements made to any node to
-which the user.name/passw0rd combination is subscribed. When an alert is
+which your account is subscribed. When an alert is
 received, it looks in the config file (loaded into memory) for the associated
 section. Importantly, if there is no section in the config file corresponding
 to the pubsub node's name (an exact match is required), ``lvalert_listen`` ignores
@@ -211,26 +219,27 @@ paths.
 Now, because you have modified the ``lvalert_listen.ini`` file, you'll need to
 restart your ``lvalert_listen`` instance. Find the PID in the process table, kill
 the existing process, and restart the listener using the command from above.
-Alternatively, if you simply launch another instance of ``lvalert_listen`` with the
-same command line as before, the existing process will die and this one will
-take its place (with the new config file loading in memory). This is because
-only one listener can exist for any (user.name, passw0rd,
-resource.name) triple *anywhere in the network*. When you launch the second
-process, one of the processes is killed automatically (although which process
+
+You can also specify a resource name in your call to ``lvalert_listen``
+using the ``-r`` flag::
+
+    lvalert_listen -a user.name -c myLVAlertListen.ini -r listener1 &
+
+If you don't specify this parameter, a random UUID is generated for the resource name.
+The important point to consider is that only one listener can exist for any 
+(user.name, passw0rd, resource.name) triple *anywhere in the network*.
+If you launch a second process with matching values of this triple,
+one of the processes is killed automatically (although which process
 dies may not be deterministic). Thus, I can kill processes running at CIT by
 creating processes at UWM with the same resource name. This can be extremely
-dangerous and annoying, so please be careful. It's generally best to specify a
-resource name for each listener, even if you expect to only have one, to ensure
-that you've thought through this. If you want to have multiple processes
-running under the same (user.name, passw0rd) pair, you will need to specify
-different resource.name options for each instance with the ``-r`` command line
-option. For example::
-
-    lvalert_listen -a user.name -b passw0rd -c myLVAlertListen.ini -r oneInstance &
-    lvalert_listen -a user.name -b passw0rd -c myLVAlertListen.ini -r twoInstance &
-
-will launch two instances of ``lvalert_listen`` (both using the same config file)
-with different resource names. They will both react to alerts and fork
+dangerous and annoying, so please be careful. If you want to directly specify
+resource names for all of your listener processes, you can do something like::
+ 
+    lvalert_listen -a user.name -c myLVAlertListen.ini -r oneInstance &
+    lvalert_listen -a user.name -c myLVAlertListen.ini -r twoInstance &
+
+This will launch two instances of ``lvalert_listen`` (both using the same
+config file) with different resource names. They will both react to alerts and fork
 processes. If each points to a different config file, I can then get multiple
 types of follow-up processes forked for the same announcement through a single
 pubsub node.
@@ -249,7 +258,7 @@ pubsub node. Create a file called ``test.txt`` and fill it with some text like::
 
 Then run::
 
-    lvalert_send -a user.name -b passw0rd -n user.name-TestNode --file test.txt
+    lvalert_send -a user.name -n user.name-TestNode --file test.txt
 
 This publishes the contents of test.txt as a string to the node
 ``user.name-TestNode``. If your listener is running in the
@@ -307,7 +316,7 @@ Create a Python executable ``iReact.py`` and fill it with the following::
     import sys
 
     alert = json.loads(sys.stdin.read())
-    print 'uid : '+alert['uid']
+    print 'uid : ' + alert['uid']
 
 Don't forget to give this executable permissions with::
 
@@ -326,11 +335,11 @@ don't have to restart the ``lvalert_listen`` instance because that still points
 Let's go ahead and send a test message in JSON format. Edit ``test.txt`` so it
 reads::
 
-    {'uid':'G12345'}
+    {"uid": "G12345"}
 
 and run::
 
-    lvalert_send -a user.name -b passw0rd --node user.name-TestNode --file test.txt
+    lvalert_send -a user.name --node user.name-TestNode --file test.txt
 
 You should see a new line in ``lvalert_user.name-TestNode.out`` which reads::
 
@@ -355,7 +364,7 @@ Open ``iReact.py`` and modify it so it reads::
     from ligo.gracedb.rest import GraceDb
 
     alert = json.loads(sys.stdin.read())
-    print 'uid : '+alert['uid']
+    print 'uid : ' + alert['uid']
 
     gdb = GraceDb() ### instantiate a GraceDB object which connects to the default server
 
@@ -367,7 +376,7 @@ Open ``iReact.py`` and modify it so it reads::
 
 Now, if we modify ``test.txt`` to::
 
-    {'uid':'G12345','alert_type':'new','far':1e-8}
+    {"uid": "G12345", "alert_type": "new", "far": 1e-8}
 
 and send it, ``iReact.py`` will try to write a log entry in GraceDB for event
 G12345. It's easy to see that you can filter alerts out (e.g.: only react to

doc/source/rest.rst

@@ -40,6 +40,7 @@ It is also available through SSH::
     git clone git@git.ligo.org:lscsoft/gracedb-client.git
 
 In order to submit patches, you should fork the repository, implement your changes, and submit a merge request.
+Patches should also be documented on the GraceDB Redmine `page <https://bugs.ligo.org/redmine/projects/gracedb>`__.
 
 .. _rest_client_basic_usage: