DOCSP-41115: get started

snooty.toml

@@ -7,16 +7,19 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
               ]
 
 toc_landing_pages = [
-    "/read"
+    "/read",
+    "/get-started"
 ]
 
 [constants]
 driver-long = "MongoDB Kotlin Sync Driver"
 driver-short = "Kotlin Sync driver"
 language = "Kotlin"
 version-number = "5.1"
+full-version = "{+version-number+}.2"
 version = "v{+version-number+}"
-patch-version-number = "{+version-number+}.0"
 mdb-server = "MongoDB Server"
 stable-api = "Stable API"
-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
+api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
+core-api = "https://mongodb.github.io/mongo-java-driver/5.1/apidocs"
+kotlin-docs = "https://kotlinlang.org"

source/get-started.txt

@@ -0,0 +1,48 @@
+.. _kotlin-sync-get-started:
+
+=======================================
+Get Started with the Kotlin Sync Driver
+=======================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :description: Learn how to create an app to connect to MongoDB deployment by using the Kotlin Sync driver.
+   :keywords: quick start, tutorial, basics
+
+.. toctree::
+
+   /get-started/download-and-install/
+   /get-started/create-a-deployment/
+   /get-started/create-a-connection-string/
+   /get-started/connect-to-mongodb/
+   /get-started/next-steps/
+
+Overview
+--------
+
+You can use the {+driver-short+} to connect to and communicate with
+MongoDB. This guide shows you how to create an application that uses
+the {+driver-short+} to connect to a MongoDB cluster hosted on
+MongoDB Atlas and interact with data.
+
+.. tip:: 
+
+   MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB
+   deployments. You can create your own free (no credit card required) MongoDB Atlas 
+   deployment by following the steps in this guide.
+
+Follow this guide to connect a sample {+language+} application to a MongoDB Atlas
+deployment. If you prefer to connect to MongoDB using a different driver or
+programming language, see the :driver:`list of official MongoDB drivers <>`.
+
+.. button:: Next: Download and Install
+   :uri: /get-started/download-and-install/

source/get-started/connect-to-mongodb.txt

@@ -0,0 +1,87 @@
+.. _kotlin-sync-connect-to-mongodb:
+
+==================
+Connect to MongoDB
+==================
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create the Application File
+
+      Create a file called ``DemoDataClassExample.kt`` in your project.
+
+      Copy the following sample code into the file and replace the value of
+      the ``<connection URI string>`` placeholder with your MongoDB
+      Atlas connection string that you saved in the preceding step.
+
+      .. literalinclude:: /includes/get-started/DemoDataClassExample.kt
+         :language: kotlin
+         :caption: DemoDataClassExample.kt
+
+      .. note::
+
+         This example uses a {+language+} data class to model MongoDB data.
+
+   .. step:: Run the Application
+
+      When you run the application, it prints the details
+      of a movie document that matches the query, as shown in the
+      following output:
+
+      .. code-block:: none
+         :copyable: false
+
+         Movie(title=Before Sunrise, year=1995, directors=[Richard Linklater])
+
+      If you don't see any output or receive an error, check whether you
+      included the proper connection string in your application. Also, confirm
+      that you successfully loaded the sample dataset into your MongoDB Atlas cluster.
+
+      After completing this step, you have a working application that uses
+      the {+driver-short+} to connect to your MongoDB cluster, run a query on the
+      sample data, and print out the result.
+
+   .. step:: Use the Document Class to Model Data (Alternative)
+
+      The preceding step demonstrates how to run a query on a sample
+      collection to retrieve data by using a {+language+} data class. This section
+      shows how to use the `Document <{+core-api+}/bson/org/bson/Document.html>`__ class  
+      to store and retrieve data from MongoDB.
+
+      In a file called ``DemoDocumentExample.kt``, paste the following sample
+      code to run a query on your sample dataset in MongoDB Atlas. Replace the
+      value of the ``<connection URI string>`` placeholder with your
+      MongoDB Atlas connection string:
+
+      .. literalinclude:: /includes/get-started/DemoDocumentExample.kt
+         :caption: DemoDocumentExample.kt
+         :language: kotlin
+
+      When you run the application, it prints the details
+      of a movie document that matches the query, as shown in the
+      following output:
+
+      .. code-block:: none
+         :copyable: false
+
+         Document{{_id=..., plot=A young man and woman ..., genres=[Drama, Romance], ...}}
+
+      If you don't see any output or receive an error, check whether you
+      included the proper connection string in your application. Also, confirm
+      that you successfully loaded the sample dataset into your MongoDB
+      Atlas cluster.
+
+After you complete these steps, you have a working application that
+uses the driver to connect to your MongoDB deployment, runs a query on
+the sample data, and prints out the result.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst
+
+.. button:: Next Steps
+   :uri: /get-started/next-steps/
+
+.. TODO add after output .. tip:: Data Classes
+.. 
+..    To learn more about using data classes to store and retrieve data,
+..    see the :ref:`fundamentals-data-classes` guide.

source/get-started/create-a-connection-string.txt

@@ -0,0 +1,63 @@
+.. _kotlin-sync-get-started-connection-string:
+
+==========================
+Create a Connection String
+==========================
+
+You can connect to your MongoDB deployment by providing a
+**connection URI**, also called a *connection string*, which
+instructs the driver on how to connect to a MongoDB deployment
+and how to behave while connected.
+
+The connection string includes the hostname or IP address and 
+port of your deployment, the authentication mechanism, user credentials 
+when applicable, and connection options.
+
+.. TODO To connect to an instance or deployment not hosted on Atlas, see
+.. :ref:`kotlin-sync-connection-targets`.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Find your MongoDB Atlas Connection String
+
+      To retrieve your connection string for the deployment that
+      you created in the :ref:`previous step <kotlin-sync-get-started-create-deployment>`,
+      log into your Atlas account, navigate to the
+      :guilabel:`Database` section, then click the :guilabel:`Connect` button
+      for your new deployment.
+
+      .. figure:: /includes/figures/atlas_connection_select_cluster.png
+         :alt: The connect button in the clusters section of the Atlas UI
+
+      Proceed to the :guilabel:`Connect your application` section, then select
+      **{+language+}** from the :guilabel:`Driver` selection menu.
+
+      Select the :guilabel:`Password (SCRAM)` authentication mechanism.
+
+      Deselect the :guilabel:`Include full driver code example` option to view
+      only the connection string.
+
+   .. step:: Copy your Connection String
+
+      Click the button on the right of the connection string to copy it to
+      your clipboard as shown in the following screenshot:
+
+      .. figure:: /includes/figures/atlas_connection_copy_string_kotlin.png
+         :alt: The connection string copy button in the Atlas UI
+
+   .. step:: Update the Placeholders
+
+      Paste this connection string into a file in your preferred text editor
+      and replace the ``<username>`` and ``<password>`` placeholders with
+      your database user's username and password.
+
+      Save this file to a safe location to use in the next step.
+
+After completing these steps, you have a connection string that
+contains your database username and password.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst
+
+.. button:: Next: Connect to MongoDB
+   :uri: /get-started/connect-to-mongodb/

source/get-started/create-a-deployment.txt

@@ -0,0 +1,32 @@
+.. _kotlin-sync-get-started-create-deployment:
+
+===========================
+Create a MongoDB Deployment
+===========================
+
+You can create a free tier MongoDB deployment on MongoDB Atlas
+to store and manage your data. MongoDB Atlas hosts and manages
+your MongoDB database in the cloud.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a Free MongoDB deployment on Atlas
+
+      Complete the :atlas:`Get Started with Atlas </getting-started>`
+      guide to set up a new Atlas account and load sample data into a new free
+      tier MongoDB deployment.
+
+   .. step:: Save your Credentials
+
+      After you create your database user, save the user's 
+      username and password to a safe location for use in an upcoming step.
+
+After you complete these steps, you have a new free tier MongoDB
+deployment on Atlas, database user credentials, and sample data loaded
+in your database.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst
+
+.. button:: Next: Create a Connection String
+   :uri: /get-started/create-a-connection-string/

source/get-started/download-and-install.txt

@@ -0,0 +1,84 @@
+.. _kotlin-sync-download-install:
+
+====================
+Download and Install
+====================
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a {+language+} Project
+
+      First, make sure that your system has {+language+} installed and
+      running on JDK 1.8 or later.
+
+      This guide shows you how to create a project and add the
+      {+driver-short+} dependencies by using Gradle or Maven. We
+      recommend that you use an integrated development
+      environment (IDE) such as IntelliJ IDEA or Eclipse IDE to
+      configure Gradle or Maven to build and run your project.
+
+      For more information on getting started with
+      {+language+} and creating your first project, see `Get started with Kotlin/JVM
+      <{+kotlin-docs+}/docs/jvm-get-started.html>`__ in the {+language+}
+      language documentation.
+
+      .. tip::
+
+         If you are not using an IDE, see the
+         `Creating New Gradle Builds
+         <https://guides.gradle.org/creating-new-gradle-builds/>`__ guide 
+         or the `Building Maven
+         <https://maven.apache.org/guides/development/guide-building-maven.html>`__ guide
+         for more information on how to set up your project.
+
+   .. step:: Add MongoDB as a Dependency
+
+      If you are using `Gradle <https://gradle.org/>`__ to manage your
+      packages, add the following entry to your ``build.gradle.kts``
+      dependencies list:
+
+      .. include:: /includes/kotlin-sync-driver-gradle-versioned.rst
+
+      If you are using `Maven <https://maven.apache.org/>`__ to manage your
+      packages, add the following entry to your ``pom.xml`` dependencies list:
+
+      .. include:: /includes/kotlin-sync-driver-maven-versioned.rst
+
+      After you configure your dependencies, ensure that they are
+      available to your project by running the dependency manager and
+      refreshing the project in your IDE.
+
+   .. step:: Add Serialization Library Dependencies
+
+      To enable the driver to convert between {+language+} objects and BSON, the
+      data format for documents in MongoDB, you must also add one or both of the
+      following serialization packages to your application:
+
+      - ``bson-kotlinx`` *(Recommended)*
+      - ``bson-kotlin``
+
+      If you are using Gradle to manage your packages, add one of the following
+      entries to your ``build.gradle.kts`` dependencies list: 
+
+      .. include:: /includes/serialization-libs-gradle-versioned.rst
+
+      If you are using Maven to manage your packages, add one of the following
+      entries to your ``pom.xml`` dependencies list:
+
+      .. include:: /includes/serialization-libs-maven-versioned.rst
+
+      After you configure your dependencies, ensure that they are available to your
+      project by running the dependency manager and refreshing the
+      project in your IDE.
+
+.. To learn more about these packages, see
+.. :ref:`kotlin-sync-serialization`.
+
+After you complete these steps, you have a new project directory
+and the driver dependencies installed.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst
+
+.. button:: Next: Create a MongoDB Deployment
+   :uri: /get-started/create-a-deployment/

source/get-started/next-steps.txt

@@ -0,0 +1,17 @@
+.. _kotlin-sync-get-started-next-steps:
+
+==========
+Next Steps
+==========
+
+Congratulations on completing the tutorial!
+
+In this tutorial, you created a {+language+} application that
+connects to a MongoDB deployment hosted on MongoDB Atlas
+and retrieves a document that matches a query.
+
+Learn more about the {+driver-short+} from the following resources:
+
+- Learn how to perform read operations in the :ref:`<kotlin-sync-read>` section.
+
+.. TODO - Learn how to perform write operations in the :ref:`<kotlin-sync-write>` section.

source/includes/get-started/DemoDataClassExample.kt

@@ -0,0 +1,24 @@
+import com.mongodb.client.model.Filters.eq
+import com.mongodb.kotlin.client.MongoClient
+
+// Create data class to represent a MongoDB document
+data class Movie(val title: String, val year: Int, val directors: List<String>)
+
+fun main() {
+    // Replace the placeholder with your MongoDB deployment's connection string
+    val uri = "<connection URI string>"
+
+    val mongoClient = MongoClient.create(uri)
+    val database = mongoClient.getDatabase("sample_mflix")
+    val collection = database.getCollection<Movie>("movies")
+
+    // Find a document with the specified title
+    val doc = collection.find(eq(Movie::title.name, "Before Sunrise")).firstOrNull()
+
+    if (doc != null) {
+        // Print the matching document
+        println(doc)
+    } else {
+        println("No matching documents found.")
+    }
+}