[Kotlin] Duplicate Titles - Connect to MongoDB

snooty.toml

@@ -9,7 +9,6 @@ intersphinx = [
 
 toc_landing_pages = [
     "/write-operations",
-    "/get-started",
     "/read",
     "/connect",
     "/indexes",

source/get-started.txt

@@ -18,14 +18,6 @@ Get Started with the Kotlin Sync Driver
    :description: Learn how to create an app to connect to MongoDB deployment by using the Kotlin Sync driver.
    :keywords: quick start, tutorial, basics
 
-.. toctree::
-
-   Download & Install </get-started/download-and-install/>
-   Create a Deployment </get-started/create-a-deployment/>
-   Create a Connection String </get-started/create-a-connection-string/>
-   Run a Sample Query </get-started/run-sample-query/>
-   Next Steps </get-started/next-steps/>
-
 Overview
 --------
 
@@ -43,3 +35,283 @@ MongoDB Atlas and interact with data.
 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 <>`.
+
+.. _kotlin-sync-download-install:
+
+Download and Install
+--------------------
+
+This section demonstrates how to create a project and add the
+{+driver-short+} dependencies by using `Gradle <https://gradle.org/>`__
+or `Maven <https://maven.apache.org/>`__.
+
+.. 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.
+
+      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.
+
+      .. 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.
+
+      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.
+
+   .. step:: Add the Driver Bill of Materials
+
+      .. _kotlin-sync-get-started-install-bom:
+
+      .. sharedinclude:: dbx/jvm/bom.rst
+
+         .. replacement:: gradle-filename
+
+            ``build.gradle.kts``
+
+   .. step:: Add MongoDB as a Dependency
+
+      If you are using Gradle 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 to manage your
+      packages, add the following entry to your ``pom.xml`` dependencies list:
+
+      .. include:: /includes/kotlin-sync-driver-maven-versioned.rst
+
+      Because you installed the BOM, you can omit a version in the
+      {+driver-short+} dependency entry. The version you specify in the
+      BOM determines the dependency versions to install.
+
+      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.
+
+.. _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.
+
+.. _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.
+
+To connect to an instance or deployment not hosted on Atlas, see the :ref:`kotlin-sync-connection-targets` guide.
+
+.. 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.
+
+.. _kotlin-sync-connect-to-mongodb:
+.. _kotlin-sync-run-sample-query:
+
+Run a Sample Query
+------------------
+
+.. 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 <https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/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.
+
+.. 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.
+
+.. _kotlin-sync-get-started-next-steps:
+
+Next Steps
+----------
+
+Congratulations on completing the tutorial!
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst
+
+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.
+
+- Learn how to perform write operations in the :ref:`<kotlin-sync-write>` section.