DOCSP-41120: connection landing (#12)

* DOCSP-41120: connection landing

* Draft

* staging

* fix error

* add intro sentences

* MM PR fixes 2

snooty.toml

@@ -8,6 +8,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
 
 toc_landing_pages = [
     "/read",
+    "/connect",
     "/indexes",
     "work-with-indexes",
 ]

source/connect.txt

@@ -0,0 +1,190 @@
+.. _kotlin-sync-connect:
+
+==================
+Connect to MongoDB
+==================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :description: Learn how to use the Kotlin Sync driver to connect to MongoDB.
+   :keywords: client, ssl, tls, localhost
+
+.. .. toctree::
+..    :titlesonly:
+..    :maxdepth: 1
+.. 
+..    /connect/mongoclient
+..    /connect/connection-targets
+..    /connect/connection-options
+..    /connect/tls
+..    /connect/network-compression
+..    /connect/server-selection
+..    /connect/stable-api
+..    /connect/csot
+
+Overview
+--------
+
+This page contains code examples that show how to use the
+{+driver-short+} to connect your application to MongoDB by specifying
+various settings. 
+
+.. .. tip::
+.. 
+..   To learn more about the connection options on this page, see the link
+..   provided in each section.
+
+To use a connection example from this page, copy the code example into the
+:ref:`sample application <kotlin-sync-connect-sample>` or your own application.
+Be sure to replace all placeholders in the code examples, such as
+``<hostname>``, with the relevant values for your MongoDB deployment.
+
+.. _kotlin-sync-connect-sample:
+
+.. include:: /includes/usage-examples/sample-app-intro.rst
+
+.. literalinclude:: /includes/usage-examples/connect-sample-app.kt
+   :language: python
+   :copyable: true
+   :linenos:
+   :emphasize-lines: 6-8
+
+Connection
+----------
+
+The following sections describe how to connect to different targets,
+such as a local instance of MongoDB or a cloud-hosted instance on Atlas.
+
+Local Deployment
+~~~~~~~~~~~~~~~~
+
+The following code shows the connection string to connect to a local
+instance of MongoDB:
+
+.. code-block:: kotlin
+
+   val uri = "mongodb://localhost:27017/"
+   val mongoClient = MongoClient.create(uri)
+
+Atlas
+~~~~~
+
+The following code shows the connection string to connect to a
+deployment hosted on Atlas:
+
+.. code-block:: kotlin
+
+   val uri = "mongodb+srv://<username>:<password>@<hostname/port>/?<options>"
+   val mongoClient = MongoClient.create(uri)
+
+Replica Set
+~~~~~~~~~~~
+
+The following code shows the connection string to connect to a
+replica set:
+
+.. code-block:: kotlin
+
+   val uri = "mongodb://<replica set member>:<port>/?replicaSet=<replica set name>"
+   val mongoClient = MongoClient.create(uri)
+
+Transport Layer Security (TLS)
+------------------------------
+
+The following sections describe how to connect to MongoDB
+while enabling the TLS protocol.
+
+Enable TLS
+~~~~~~~~~~
+
+The following tabs demonstrate how to enable TLS on a connection:
+
+.. include:: /includes/connect/tls-tabs.rst
+
+.. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in
+.. the TLS configuration guide.
+
+Disable Hostname Verification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to disable hostname verification when
+connecting by using TLS:
+
+.. include:: /includes/connect/disable-host-verification-tabs.rst
+
+.. To learn more about disabling hostname verification, see :ref:`kotlin-sync-insecure-tls` in
+.. the TLS configuration guide.
+
+Network Compression
+-------------------
+
+The following sections describe how to connect to MongoDB
+while specifying network compression algorithms.
+
+Compression Algorithms
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to specify all available compressors
+while connecting to MongoDB:
+
+.. include:: /includes/connect/compression-tabs.rst
+
+.. To learn more about specifying compression algorithms, see
+.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide.
+
+zlib Compression Level
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to specify a compression level for
+the ``zlib`` compressor:
+
+.. include:: /includes/connect/zlib-level-tabs.rst
+
+.. To learn more about setting the zlib compression level, see
+.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide.
+
+Server Selection
+----------------
+
+The following code shows a connection string that specifies a server
+selection function:
+
+.. code-block:: kotlin
+
+   val client = MongoClient.create("mongodb://<username>:<password>@<hostname>:<port>",
+                                server_selector=<selector function>)
+
+.. To learn more about customizing server selection, see
+.. :ref:`kotlin-sync-server-selection`.
+
+{+stable-api+}
+--------------
+
+The following code shows how to specify Stable API settings within a
+``MongoClientSettings`` instance:
+
+.. code-block:: kotlin
+
+   val serverApi = ServerApi.builder()
+       .version(ServerApiVersion.V1)
+       .build()
+
+   val uri = "<connection string>"
+
+   val settings = MongoClientSettings.builder()
+       .applyConnectionString(ConnectionString(uri))
+       .serverApi(serverApi)
+       .build()
+
+   val client = MongoClient.create(settings)
+
+.. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`.

source/includes/connect/compression-tabs.rst

@@ -0,0 +1,27 @@
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: kotlin
+
+         val settings = MongoClientSettings.builder()
+             .applyConnectionString(ConnectionString("<connection string>"))
+             .compressorList(
+                 listOf(
+                     MongoCompressor.createSnappyCompressor(),
+                     MongoCompressor.createZlibCompressor(),
+                     MongoCompressor.createZstdCompressor())
+             )
+             .build()
+
+         val mongoClient = MongoClient.create(settings)
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: kotlin
+
+         val uri = ConnectionString("mongodb+srv://<user>:<password>@<cluster-url>/?compressors=snappy,zlib,zstd")
+         
+         val mongoClient = MongoClient.create(uri)

source/includes/connect/disable-host-verification-tabs.rst

@@ -0,0 +1,24 @@
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: kotlin
+
+         val settings = MongoClientSettings.builder()
+             .applyConnectionString(ConnectionString("<connection string>"))
+             .applyToSslSettings { builder ->
+                 builder.enabled(true)
+                 builder.invalidHostNameAllowed(true)
+             }
+             .build()
+         val mongoClient = MongoClient.create(settings);
+
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: kotlin
+
+         val uri = "mongodb://<username>:<password>@<hostname>:<port>/?"tls=true&tlsAllowInvalidHostnames=true"
+         val mongoClient = MongoClient.create(uri)

source/includes/connect/tls-tabs.rst

@@ -0,0 +1,24 @@
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: kotlin
+
+         val settings = MongoClientSettings.builder()
+             .applyConnectionString(ConnectionString("<connection string>"))
+             .applyToSslSettings { builder ->
+                 builder.enabled(true)
+             }
+             .build()
+             
+         val mongoClient = MongoClient.create(settings)
+
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: kotlin
+
+         val uri = "mongodb+srv://<user>:<password>@<cluster-url>?tls=true"
+         val mongoClient = MongoClient.create(uri)

source/includes/connect/zlib-level-tabs.rst

@@ -0,0 +1,26 @@
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: kotlin
+
+         val zlib = MongoCompressor.createZlibCompressor()
+
+         val settings = MongoClientSettings.builder()
+             .applyConnectionString(ConnectionString(uri))
+             .compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, <level>)))
+             .build()
+
+         val mongoClient = MongoClient.create(settings)
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: kotlin
+
+         val uri = "mongodb://<username>:<password>@<hostname>:<port>/?" +
+                   "compressors=zlib" +
+                   "zlibCompressionLevel=<zlib compression level>"
+         
+         val mongoClient = MongoClient.create(uri)

source/includes/usage-examples/connect-sample-app.kt

@@ -0,0 +1,15 @@
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.Document
+
+fun main() {
+
+    // Start example code here
+
+    // End example code here
+
+    val database = mongoClient.getDatabase("admin")
+
+    val command = Document("ping", 1)
+    val commandResult = database.runCommand(command)
+    println("Pinged your deployment. You successfully connected to MongoDB!")
+}

source/index.txt

@@ -13,6 +13,7 @@
 
 .. toctree::
 
+   /connect
    /write-operations
    /read
    /indexes
@@ -47,6 +48,12 @@ Quick Start
 Learn how to establish a connection to MongoDB Atlas and begin
 working with data in the :ref:`Quick Start <kotlin-sync-quick-start>` section.
 
+Connect to MongoDB
+------------------
+
+Learn how to create and configure a connection to a MongoDB deployment
+in the :ref:`kotlin-sync-connect` section.
+
 What's New
 ----------