DOCSP-13865 distinct usage examples (#25)

* added distinct usage examples page

Author: kyuan-mongodb

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

@@ -0,0 +1,47 @@
+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 distinct
+	coll := client.Database("sample_mflix").Collection("movies")
+	filter := bson.D{{"directors", "Natalie Portman"}}
+
+	results, err := coll.Distinct(context.TODO(), "title", filter)
+	// end distinct
+
+	if err != nil {
+		panic(err)
+	}
+
+	// When you run this file, it should print: 
+	// A Tale of Love and Darkness
+	// New York, I Love You
+	for _, result := range results {
+		fmt.Println(result)
+	}
+}

source/usage-examples.txt

@@ -17,12 +17,12 @@ Usage Examples
    /usage-examples/delete-operations
    /usage-examples/count
    /usage-examples/command
+   /usage-examples/distinct
 
 ..
    /usage-examples/insert-operations
    /usage-examples/bulkWrite
    /usage-examples/watch
-   /usage-examples/distinct
 
 
 Overview

source/usage-examples/distinct.txt

@@ -3,3 +3,45 @@ Retrieve Distinct Values of a Field
 ===================================
 
 .. default-domain:: mongodb
+
+You can retrieve a list of distinct values for a field across a
+collection by using the ``Distinct()`` method. 
+
+The following example specifies a query filter and a field name to the
+``Distinct()`` method, which matches documents in the ``movies``
+collection where the ``directors`` field contains "Natalie Portman" and
+returns distinct values of the ``title`` field from the matched documents. 
+
+.. include:: /includes/usage-examples/run-example-tip.rst
+
+.. literalinclude:: /includes/usage-examples/code-snippets/distinct.go
+   :start-after: begin distinct
+   :end-before: end distinct
+   :emphasize-lines: 4
+   :language: go
+   :dedent:
+
+Click `here <{+example+}/distinct.go>`__ to see a fully runnable example.
+
+Expected Result
+---------------
+
+The example returns an empty slice of an ``interface`` type that
+contains the following values: 
+
+.. code-block:: none
+   :copyable: false
+
+    A Tale of Love and Darkness
+    New York, I Love You
+
+Additional Information
+----------------------
+
+For more information on retrieving distinct values, see our guide on
+<TODO: Distinct Fundamentals>. 
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+`Distinct() <{+godocs+}/mongo#Collection.Distinct>`__