DOCSP-30512: insert one usage ex (#75)

(cherry picked from commit ef51d9a)

Author: rustagir

source/includes/usage-examples/code-snippets/insert-one-async.rs

@@ -0,0 +1,31 @@
+use std::env;
+use mongodb::{ bson::doc, Client, Collection };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    borough: String,
+    cuisine: String,
+    name: 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 doc = Restaurant {
+        name: "Sea Stone Tavern".to_string(),
+        cuisine: "Greek".to_string(),
+        borough: "Queens".to_string(),
+    };
+
+    let res = my_coll.insert_one(doc, None).await?;
+    println!("Inserted a document with _id: {}", res.inserted_id);
+
+    Ok(())
+}

source/includes/usage-examples/code-snippets/insert-one-sync.rs

@@ -0,0 +1,30 @@
+use std::env;
+use mongodb::{ bson::doc, sync::{ Client, Collection } };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    borough: String,
+    cuisine: String,
+    name: 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 doc = Restaurant {
+        name: "Sea Stone Tavern".to_string(),
+        cuisine: "Greek".to_string(),
+        borough: "Queens".to_string(),
+    };
+
+    let res = my_coll.insert_one(doc, None)?;
+    println!("Inserted a document with _id: {}", res.inserted_id);
+
+    Ok(())
+}

source/usage-examples.txt

@@ -14,6 +14,7 @@ Usage Examples
 
    /usage-examples/findOne
    /usage-examples/find
+   /usage-examples/insertOne
    /usage-examples/replace
    /usage-examples/deleteMany
    /usage-examples/count
@@ -92,12 +93,12 @@ Available Usage Examples
 
 - :ref:`Find a Document <rust-find-one-usage>`
 - :ref:`Find Multiple Documents <rust-find-usage>`
+- :ref:`Insert a Document <rust-insert-one-usage>`
 - :ref:`Replace a Document <rust-replace-usage>`
 - :ref:`Delete Multiple Documents <rust-delete-many-usage>`
 - :ref:`Count Documents <rust-count-usage>`
 
 .. TODO: add Usage Example pages as they are created
-    - :ref:`Insert a Document <rust-insert-one-usage>`
     - :ref:`Insert Multiple Documents <rust-insert-many-usage>`
     - :ref:`Update a Document <rust-update-one-usage>`
     - :ref:`Update Multiple Documents <rust-update-many-usage>`

source/usage-examples/count.txt

@@ -37,10 +37,13 @@ example uses the ``count_documents()`` method to count the number of
 documents that match a query filter. The filter matches documents in which
 the value of the ``name`` field includes the string ``"Sunset"``.
 
+Select the **Asynchronous** or **Synchronous** tab to see the
+corresponding code for each runtime:
+
 .. tabs::
 
    .. tab:: Asynchronous
-      :tabid: find-async
+      :tabid: count-async
 
       .. io-code-block::
          :copyable: true
@@ -58,7 +61,7 @@ the value of the ``name`` field includes the string ``"Sunset"``.
             Number of matching documents: 10
 
    .. tab:: Synchronous
-      :tabid: find-sync
+      :tabid: count-sync
 
       .. io-code-block::
          :copyable: true

source/usage-examples/deleteMany.txt

@@ -36,7 +36,8 @@ This example passes a query filter as a parameter to the ``delete_many()`` metho
 The filter matches documents where the value of the ``borough`` field is ``"Manhattan"``
 and the value of the ``address.street`` field is ``"Broadway"``.
 
-Select the **Asynchronous** or **Synchronous** tab to see corresponding code for each runtime:
+Select the **Asynchronous** or **Synchronous** tab to see the
+corresponding code for each runtime:
 
 .. tabs::
 
@@ -58,7 +59,7 @@ Select the **Asynchronous** or **Synchronous** tab to see corresponding code for
             Deleted documents: 615
 
    .. tab:: Synchronous
-      :tabid: find-sync
+      :tabid: delete-many-sync
 
       .. io-code-block::
          :copyable: true

source/usage-examples/find.txt

@@ -33,7 +33,8 @@ in the collection.
 The following code passes a query filter as a parameter to the ``find()`` method. The
 filter matches documents in which the value of the ``cuisine`` field is ``"French"``.
 
-Select the **Asynchronous** or **Synchronous** tab to see corresponding code for each runtime:
+Select the **Asynchronous** or **Synchronous** tab to see the
+corresponding code for each runtime:
 
 .. tabs::
 

source/usage-examples/findOne.txt

@@ -29,12 +29,13 @@ struct with the data from the retrieved document.
 This example uses a query filter that matches documents in which the value of the
 ``name`` field is ``"Tompkins Square Bagels"``.
 
-Select the **Asynchronous** or **Synchronous** tab to see corresponding code for each runtime:
+Select the **Asynchronous** or **Synchronous** tab to see the
+corresponding code for each runtime:
 
 .. tabs::
 
    .. tab:: Asynchronous
-      :tabid: find-async
+      :tabid: find-one-async
 
       .. io-code-block::
          :copyable: true
@@ -55,7 +56,7 @@ Select the **Asynchronous** or **Synchronous** tab to see corresponding code for
             )
 
    .. tab:: Synchronous
-      :tabid: find-sync
+      :tabid: find-one-sync
 
       .. io-code-block::
          :copyable: true

source/usage-examples/insertOne.txt

@@ -0,0 +1,72 @@
+.. _rust-insert-one-usage:
+
+=================
+Insert a Document
+=================
+
+You can insert a document into a collection by calling the `insert_one()
+<{+api+}/struct.Collection.html#method.insert_one>`__ method on a
+``Collection`` instance.
+
+You must insert a document of the same type that you parameterized your
+``Collection`` instance with. For example, if you parameterized your
+collection with the ``MyStruct`` struct, pass a ``MyStruct``
+instance as a parameter to the ``insert_one()`` method to insert a
+document. To learn more about specifying a type parameter, see the
+:ref:`Collection Parameterization <rust-coll-parameterization>` section
+of the Databases and Collections guide.
+
+The ``insert_one()`` method returns an `InsertOneResult
+<{+api+}/results/struct.InsertOneResult.html>`__ type which contains the
+``_id`` field of the newly inserted document.
+
+To learn more about the ``insert_one()`` method, see the
+:ref:`rust-insert-guide` guide.
+
+Example
+-------
+
+This example inserts a document into the ``restaurants`` collection of
+the ``sample_restaurants`` database. The example uses a ``Restaurant``
+struct that has ``name``, ``borough``, and ``cuisine`` fields to model
+documents in the collection.
+
+The following code creates a ``Restaurant`` instance and inserts it into
+the collection.
+
+Select the **Asynchronous** or **Synchronous** tab to see the
+corresponding code for each runtime:
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: insert-one-async
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/insert-one-async.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            Inserted a document with _id: ObjectId("...")
+
+   .. tab:: Synchronous
+      :tabid: insert-one-sync
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/insert-one-sync.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            Inserted a document with _id: ObjectId("...")

source/usage-examples/replace.txt

@@ -32,12 +32,15 @@ struct that has ``name``, ``borough``, and ``cuisine`` fields to model
 documents in the collection.
 
 The following code replaces a document in which the value of the
-``name`` field is ``"Landmark Coffee Shop"`` with a new document:
+``name`` field is ``"Landmark Coffee Shop"`` with a new document.
+
+Select the **Asynchronous** or **Synchronous** tab to see the
+corresponding code for each runtime:
 
 .. tabs::
 
    .. tab:: Asynchronous
-      :tabid: find-async
+      :tabid: replace-async
 
       .. io-code-block::
          :copyable: true
@@ -54,7 +57,7 @@ The following code replaces a document in which the value of the
             Replaced documents: 1
 
    .. tab:: Synchronous
-      :tabid: find-sync
+      :tabid: replace-sync
 
       .. io-code-block::
          :copyable: true