DOCSP-13867 watch usage example (#27)

* added watch usage example page

Author: kyuan-mongodb

source/includes/usage-examples/code-snippets/watch.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/mongo"
+	"go.mongodb.org/mongo-driver/mongo/options"
+)
+
+func main() {
+	var uri string
+	if uri = os.Getenv("MONGODB_URI"); uri == "" {
+		log.Fatal("You must set your 'MONGODB_URI' environmental variable. See\n\t https://docs.mongodb.com/drivers/go/current/usage-examples/")
+	}
+
+	client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		if err = client.Disconnect(context.TODO()); err != nil {
+			panic(err)
+		}
+	}()
+
+	// begin watch
+	coll := client.Database("insertDB").Collection("haikus")
+	pipeline := mongo.Pipeline{bson.D{{"$match", bson.D{{"operationType", "insert"}}}}}
+	cs, err := coll.Watch(context.TODO(), pipeline)
+	if err != nil {
+		panic(err)
+	}
+	defer cs.Close(context.TODO())
+
+	fmt.Println("Waiting For Change Events. Insert something in MongoDB!")
+
+	for cs.Next(context.TODO()) {
+		var event bson.D
+		if err := cs.Decode(&event); err != nil {
+			panic(err)
+		}
+		fmt.Println(event[3].Value)
+	}
+	if err := cs.Err(); err != nil {
+		panic(err)
+	}
+	// end watch
+}

source/usage-examples.txt

@@ -20,11 +20,10 @@ Usage Examples
    /usage-examples/struct-tagging
    /usage-examples/distinct
    /usage-examples/bulkWrite
+   /usage-examples/watch
 
 ..
    /usage-examples/insert-operations
-   /usage-examples/watch
-
 
 Overview
 --------

source/usage-examples/watch.txt

@@ -4,7 +4,52 @@ Watch for Changes
 
 .. default-domain:: mongodb
 
-You can keep track of changes to data in MongoDB, such as changes to a
-collection, database, or deployment, by opening a **change stream**. A change
-stream allows applications to watch for changes to data and react to them.
-The change stream returns **change event** documents when changes occur.
+You can open a change stream on a ``MongoCollection``,
+``MongoDatabase``, or ``MongoClient`` by using the ``Watch()`` method.
+
+The following example uses the ``Watch()`` method, to open a change
+stream on the ``haikus`` collection and prints inserted documents:
+
+.. include:: /includes/usage-examples/run-example-tip.rst
+
+.. literalinclude:: /includes/usage-examples/code-snippets/watch.go
+   :start-after: begin watch
+   :end-before: end watch
+   :emphasize-lines: 3
+   :language: go
+   :dedent:
+
+Click `here <{+example+}/watch.go>`__ to see a fully runnable example.
+
+Expected Result
+---------------
+
+After you run the preceding example, run the :doc:`Insert a
+Document usage example </usage-examples/insertOne>` in a different
+shell. Once you run the insert operation, you should see output similar
+to the following:
+
+.. code-block:: json
+   :copyable: false
+
+   // results truncated 
+   [{_id ObjectID("...")} {title Record of ...} {text No bytes, no problem....}]
+
+.. important::
+
+   Make sure to shut down this usage example once you finish by closing
+   your terminal.  
+
+Additional Information
+----------------------
+
+For more information on opening a change stream and handling
+potential errors, see the following guides: 
+
+- Go Driver <TODO: Change Stream Guide>
+- MongoDB Server Manual :manual:`Change Streams Documentation </changeStreams>`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+`Watch() <{+godocs+}/mongo#Collection.Watch>`__