DOCSP-30511: Find usage example (#64)

(cherry picked from commit 62f5053)

Author: norareidy

source/includes/usage-examples/code-snippets/find-async.rs

@@ -0,0 +1,36 @@
+use mongodb::{ 
+    bson::doc,
+    Client,
+    Collection
+};
+use futures::TryStreamExt;
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+    cuisine: String,
+}
+
+#[tokio::main]
+async fn main() -> mongodb::error::Result<()> {
+    let uri = "<connection string>";
+    let client = Client::with_uri_str(uri).await?;
+
+    let my_coll: Collection<Restaurant> = client
+        .database("sample_restaurants")
+        .collection("restaurants");
+
+    let mut cursor = my_coll.find(
+        doc! { "cuisine": "French" },
+        None
+    ).await?;
+
+    while let Some(doc) = cursor.try_next().await? {
+        println!("{:?}", doc);
+    }
+
+    Ok(())
+}
+
+

source/includes/usage-examples/code-snippets/find-sync.rs

@@ -0,0 +1,31 @@
+use mongodb::{
+    bson::{doc, Document},
+    sync::{Client, Collection}
+};
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+    cuisine: String,
+}
+
+fn main() -> mongodb::error::Result<()> {
+    let uri = "<connection string>";
+    let client = Client::with_uri_str(uri)?;
+
+    let my_coll: Collection<Restaurant> = client
+        .database("sample_restaurants")
+        .collection("restaurants");
+
+    let mut cursor = my_coll.find(
+        doc! { "cuisine": "French" },
+        None
+    )?;
+    
+    for result in cursor {
+        println!("{:?}", result?);
+      }
+
+    Ok(())
+}

source/usage-examples.txt

@@ -10,6 +10,10 @@ Usage Examples
    :depth: 1
    :class: singlecol
 
+.. toctree::
+
+   /usage-examples/find
+
 Overview
 --------
 
@@ -77,12 +81,13 @@ up an account and a cluster, see the :atlas:`Get Started with Atlas Guide
 After completing these steps, you can see the output described in the **Expected Output** section
 of the corresponding usage example.
 
-.. Available Usage Examples
-.. ------------------------
+Available Usage Examples
+------------------------
 
+- :ref:`Find Multiple Documents <rust-find-usage>`
+  
 .. TODO: add Usage Example pages as they are created
     - :ref:`Find a Document <rust-find-one-usage>`
-    - :ref:`Find Multiple Documents <rust-find-usage>`
     - :ref:`Insert a Document <rust-insert-one-usage>`
     - :ref:`Insert Multiple Documents <rust-insert-many-usage>`
     - :ref:`Update a Document <rust-update-one-usage>`

source/usage-examples/find.txt

@@ -0,0 +1,85 @@
+.. _rust-find-usage:
+
+=======================
+Find Multiple Documents
+=======================
+
+You can query for multiple documents in a collection by calling the ``find()``
+method on a ``Collection`` instance. 
+
+Pass a query filter to the ``find()`` method to return documents in the collection
+that match the filter. If you do not include a filter, MongoDB returns all the
+documents in the collection.
+
+The ``find()`` method returns a ``Cursor`` type, which you can iterate through
+to retrieve individual documents.
+
+Example
+-------
+
+This example finds documents from the ``sample_restaurants.restaurants`` collection
+that match a query filter. The example uses a ``Restaurant`` struct that has ``name``
+and ``cuisine`` fields to model the documents in the collection.
+
+The following code passes a query filter as a parameter to the ``find()`` method. The
+filter matches documents where the value of the ``cuisine`` field is ``"French"``.
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: find-async
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/find-async.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            // Results truncated
+            ...
+            Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" }
+            Restaurant { name: "Calliope", cuisine: "French" }
+            ...
+
+   .. tab:: Synchronous
+      :tabid: find-sync
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/find-sync.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            // Results truncated
+            ...
+            Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" }
+            Restaurant { name: "Calliope", cuisine: "French" }
+            ...
+
+Additional Information
+----------------------
+
+To learn more about retrieving documents, see the :ref:`rust-retrieve-guide` guide.
+
+To learn more about using cursors, see the :ref:`rust-cursor-guide` guide.
+
+To learn more about using query filters, see the :ref:`rust-query-guide` guide.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods and types mentioned on this
+page, see the following API documentation:
+
+- `find() <{+api+}/struct.Collection.html#method.find>`__
+- `Cursor <{+api+}/struct.Cursor.html>`__