DOCSP-13866: update findOne to new format (#33)

* wip

* DOCSP-13866:  update findOne to new format

* remove python2 intersphinx

* clean up info

* Update source/usage-examples/findOne.txt

Co-authored-by: kyuan-mongodb <[email protected]>

* wip

Co-authored-by: kyuan-mongodb <[email protected]>

Author: terakilobyte

snooty.toml

@@ -9,7 +9,6 @@ toc_landing_pages = [
 intersphinx = [
   "https://docs.mongodb.com/manual/objects.inv",
   "https://docs.atlas.mongodb.com/objects.inv",
-  "https://docs.python.org/2/python2.inv"
 ]
 
 [constants]

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

@@ -0,0 +1,49 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"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 findOne
+	coll := client.Database("sample_mflix").Collection("movies")
+	var result bson.D
+	err = coll.FindOne(context.TODO(), bson.D{{"title", "The Room"}}).Decode(&result)
+	// end findOne
+	if err != nil {
+		if err == mongo.ErrNoDocuments {
+			// This error means your query did not match any documents.
+			return
+		}
+		panic(err)
+	}
+	// use Map() to quickly convert bson.D to a map
+	output, err := json.MarshalIndent(result.Map(), "", "    ")
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("%s\n", output)
+}

source/usage-examples/find.txt

@@ -20,7 +20,7 @@ which matches documents in the ``zips`` collection where the value of the
    :language: go
    :dedent:
 
-Click here **<TODO: github link to file>** to see a fully runnable example.
+Click `here <{+example+}/find.go>`__ to see a fully runnable example.
 
 Expected Result
 ---------------

source/usage-examples/findOne.go

@@ -4,100 +4,51 @@ Find a Document
 
 .. default-domain:: mongodb
 
-You can retrieve a single document from your collection with the
-``Collection.FindOne()`` method.
+You can retrieve a single document from a collection by using the
+``FindOne()`` method.
 
-..
-   method
+The following example passes a query filter to the ``FindOne()`` method,
+which matches documents in the ``movies`` collection where the value
+of the ``title`` field is *The Room*, returning the first document found.
 
-The ``FindOne()`` method takes a filter document. Calling the ``FindOne()``
-method retrieves a document from your MongoDB instance that matches your
-filter document. If you pass the ``FindOne()`` method an empty filter document,
-MongoDB considers your entire collection when retrieving your document. For more
-information on documents in the MongoDB Go driver, see our
-:doc:`guide on data formats </fundamentals/data-formats>`.
+.. include:: /includes/usage-examples/run-example-tip.rst
 
-You must pass the ``FindOne()`` method a ``context.Context`` interface type
-value. For more information on the ``context.Context`` interface and the
-``context`` package, see our :doc:`guide on contexts </fundamentals/context>`.
-
-..
-   options
-
-You can specify options that change the behavior of the ``FindOne()`` method.
-One example of an option is **sort**, which instructs your MongoDB instance to
-order the matching documents of your collection before it retrieves the
-first document. Another example of an option is a **projection**, which
-specifies or restricts the fields in your returned document. You can specify
-options by passing the ``FindOne()`` method a pointer to a ``FindOneOptions`` struct.
-You can configure a ``FindOneOptions`` struct by using setter methods such as the
-``FindOneOptions.SetProjection()`` method. For more information on the sort option,
-:doc:`see our guide on sorting </fundamentals/crud/read-operations/sort/>`.
-For more information on the projection option,
-<TODO:>.
-
-..
-   return
-
-If the query filter you specified in your ``FindOne()`` method call matches one
-or more documents in your collection, it returns the first matched result. The
-return type ``SingleResult`` represents a single document returned from a query
-to a MongoDB instance. You can call the ``SingleResult.Decode()`` method
-to unmarshal a ``SingleResult`` struct type into a variable. Pass the ``Decode()``
-method a pointer to the variable that you would like to contain your returned
-document.
-
-..
-   error
-
-When you call the ``Decode()`` method to unmarshal your result, the method
-returns an ``error`` interface type which can contain one of the following
-values:
+.. literalinclude:: /includes/usage-examples/code-snippets/findOne.go
+   :start-after: begin findOne
+   :end-before: end findOne
+   :language: go
+   :dedent:
+   :emphasize-lines: 3
 
-- ``nil`` if a document matched your query, and there were no errors retrieving
-  the document.
-- ``ErrNoDocuments`` if no documents matched your query.
-- If the driver retrieved your document but could not unmarshal your result, the
-  ``Decode()`` method returns the unmarshaling error.
-- If there was an error retrieving your document during execution of the
-  ``FindOne()`` method, the error propagates to the ``Decode()`` method and
-  the ``Decode()`` method returns the error.
+Click `here <{+example+}/findOne.go>`__ to see a fully runnable example.
 
-Example
--------
+Expected Result
+---------------
 
-The following code example retrieves a single document from the ``movies``
-collection. It uses the following arguments for the ``FindOne()`` method:
+After you run the code example, you should see output similar to:
 
-- An empty **Context** instance returned from the ``context.TODO()`` function.
-- A **filter document** that only matches movies with the title exactly matching
-  the text ``"The Room"``.
-- **Options** that specify a **sort** of matched documents in
-  descending order by rating, such that the first document has the highest
-  rating. The options also specify a **projection** for the results so
-  that the MongoDB instance only sends the ``title`` and ``imdb`` fields of
-  the retrieved document.
+.. code-block:: json
+   :copyable: False
 
-.. literalinclude:: findOne.go
-   :language: go
+   {
+     ...
+     "title": "The Room",
+     "year": 2003,
+     ...
+   }
 
-If you run the example above, you should see a result that looks like this:
+Additional Information
+----------------------
 
-.. literalinclude:: findOne-output.txt
-   :language: none
+For more information on specifying query filters and
+handling potential errors, see our guide on **<TODO: retrieve data
+fundamental page>**.
 
-.. include:: /includes/sample-data-note.rst
+For more information on query operators,
+see the :manual:`MongoDB query operator reference documentation
+</reference/operator/query/>`.
 
-For more information on the methods, interfaces, structs, and functions
-mentioned on this page, see the following API documentation:
+API Documentation
+~~~~~~~~~~~~~~~~~
 
-- :go-api:`Collection.FindOne() <mongo#Collection.FindOne>`
-- `Context <https://pkg.go.dev/context#Context>`__
-- :go-api:`FindOneOptions <mongo/options#FindOneOptions>`
-- :go-api:`FindOneOptions.SetProjection() <mongo/options#FindOneOptions.SetProjection>`
-- :go-api:`options.FindOne() <mongo/options#FindOne>`
-- :go-api:`SingleResult <mongo#SingleResult>`
-- :go-api:`SingleResult.Decode() <mongo#SingleResult.Decode>`
-- `context.TODO() <https://pkg.go.dev/context#TODO>`__
-- :go-api:`bson.D <bson#D>`
-- :go-api:`bson.MarshalExtJSON() <bson#MarshalExtJSON>`
+`FindOne() <{+godocs+}/mongo#Collection.FindOne>`__