Revert "DOCSP-37496 - FAQ (#35)"

This reverts commit 8fba8fe.

Author: mongoKart

snooty.toml

@@ -1,6 +1,10 @@
 name = "pymongo"
 title = "PyMongo"
 toc_landing_pages = [
+    "/get-started", 
+    "/write-operations", 
+    "/read", 
+    "/connect"
 ]
 
 intersphinx = [
@@ -12,13 +16,16 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
 [constants]
 driver-short = "PyMongo"
+driver-long = "PyMongo, the MongoDB synchronous Python driver,"
 language = "Python"
 mongo-community = "MongoDB Community Edition"
 mongo-enterprise = "MongoDB Enterprise Edition"
-docs-branch = "master"                                                                                          # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
+docs-branch = "master"                                                                                           # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
 version-number = "4.6"
-patch-version-number = "{+version-number+}.1"                                                                   # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
+patch-version-number = "{+version-number+}.1"                                                                    # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
 version = "v{+version-number+}"
 example = "https://raw.githubusercontent.com/mongodb/docs-pymongo/{+docs-branch+}/source/includes/code-examples"
 stable-api = "Stable API"
-api-root = "https://pymongo.readthedocs.io/en/{+patch-version-number+}/api/index.html"
+api-root = "https://pymongo.readthedocs.io/en/{+patch-version-number+}/api/"
+string-data-type = "``str``"
+int-data-type = "``int``"

source/connect.txt

@@ -0,0 +1,18 @@
+.. _pymongo-connect:
+
+==================
+Connect to MongoDB
+==================
+
+.. meta::
+   :description: Learn how to use (+driver-short+} to connect to from MongoDB.
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /connect/tls
+   /connect/client-certificates
+
+- :ref:`pymongo-tls`
+- :ref:`pymongo-client-certificates`

source/fundamentals/connection/connect.txt renamed to source/connect/connect.txt

@@ -0,0 +1,215 @@
+.. _pymongo-connection-options:
+
+==================
+Connection Options
+==================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, Atlas, settings, configure
+
+Overview
+--------
+
+This section describes the MongoDB connection and authentication options
+available in {+driver-short+}. You can configure your connection using either
+the connection URI or arguments to the ``MongoClient`` constructor.
+
+.. _pymongo-connection-uri:
+
+Using the Connection URI
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you pass a connection URI to the ``MongoClient`` constructor, you can include
+connection options in the string as ``<name>=<value>`` pairs. In the following example,
+the connection URI contains the ``connect_timeout`` option with a value of ``60000``
+and the ``tls`` option with a value of ``true``:
+
+.. literalinclude:: /includes/connect/local_connection_config.py
+   :language: python
+   :dedent:
+   :start-after: # start local connection config
+   :end-before: # end local connection config
+
+.. _pymongo-mongo-client-settings:
+
+Using a ``MongoClient``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can pass connection options as arguments to the ``MongoClient`` constructor
+instead of including them in your connection URI.
+Configuring the connection this way makes it easier to
+change settings at runtime and helps you catch errors during compilation.
+The following example shows how to use the ``MongoClient`` constructor to set
+connection options:
+
+.. literalinclude:: /includes/connect/mongoclient_settings_config.py
+   :language: python
+   :dedent:
+   :start-after: # start mongo client settings config
+   :end-before: # end mongo client settings config
+
+Connection Options
+------------------
+
+The following sections describe the connection options available in {+driver-short+}.
+If a ``MongoClient`` parameter maps to more than one
+option in the connection string, the **Connection URI Example** shows all
+relevant options.
+
+.. todo: .. note::
+   If you're using a query parameter for a time duration, the value must be in
+   milliseconds. For example, to specify 60 seconds, use the value ``60000``. If you're
+   using a ``MongoClientSettings`` object for a time duration, use the appropriate
+   ``TimeSpan`` value.
+
+Network Compression
+~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Connection Option
+     - Description
+     
+   * - **compressors**
+     - | The preferred compression types, in order, for wire-protocol messages sent to
+       | or received from the server. The driver uses the first of these compression types
+       | that the server supports.
+       |
+       | **Data Type**: {+string-data-type+}
+       | **Default**: ``None``
+       | **MongoClient Example**: ``compressors = "snappy,zstd,zlib"``
+       | **Connection URI Example**: ``compressors=snappy,zstd,zlib``
+
+   * - **zlibCompressionLevel**
+     - | The compression level for zlib to use. This option accepts
+       | an integer value between ``-1`` and ``9``:
+       | 
+       | - **-1:** (Default). zlib uses its default compression level (usually ``6``).
+       | - **0:** No compression.
+       | - **1:** Fastest speed but lowest compression.
+       | - **9:** Best compression but slowest speed.
+       |
+       | **Data Type**: {+int-data-type+}
+       | **Default**: ``-1``
+       | **MongoClient Example**: ``zlibCompressionLevel = 3``
+       | **Connection URI Example**: ``zlibCompressionLevel=3``
+
+Server Selection
+~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Connection Option
+     - Description
+
+   * - **server_selector**
+     - | A user-defined Python function called by {+driver-short+} to choose the server
+       | to run an operation against. For more information, see
+       | :ref:`<pymongo-server-selection>`.
+       |
+       | **Data Type**: ``callable``
+       | **Default**: ``None``
+       | **MongoClient Example**: ``server_selector = your_function``
+       | **Connection URI Example**: N/A
+
+.. _secondary-reads:
+
+Secondary Reads
+---------------
+
+By default, an instance of ``MongoClient`` sends queries to
+the primary member of the replica set. To use secondary members for queries instead, change
+the read preference as shown in the following example:
+
+.. code-block:: python
+
+   >>> client = MongoClient(
+   ...     'localhost:27017',
+   ...     replicaSet='foo',
+   ...     readPreference='secondaryPreferred')
+   >>> client.read_preference
+   SecondaryPreferred(tag_sets=None)
+
+Now the ``MongoClient`` sends all queries to the secondary members of the replica set. If there are
+no secondary members, the client uses the primary member as a fallback. If you have
+queries you would prefer to never send to the primary, you can specify that
+using the ``secondary`` read preference.
+
+.. _health-monitoring:
+
+Health Monitoring
+-----------------
+
+When you initialize a ``MongoClient``, it launches background threads to
+monitor the replica set for the following changes:
+
+- Health: Detect when a member goes down or comes up, or if a different member
+  becomes primary.
+- Configuration: Detect when members are added or removed, and detect changes
+  in members' tags.
+- Latency: Track a moving average of each member's ping time.
+
+Replica-set monitoring ensures that queries are continually routed to the proper
+members as the state of the replica set changes.
+
+.. _mongos-load-balancing:
+
+``mongos`` Load Balancing
+-------------------------
+
+You can configure an instance of ``~pymongo.mongo_client.MongoClient``
+with a list of ``mongos`` server addresses:
+
+.. code-block:: python
+
+   >> client = MongoClient('mongodb://host1,host2,host3')
+
+Each member of the list must be a single ``mongos`` server. Multi-homed and round
+robin DNS addresses are **not** supported. The client continuously
+monitors the availability of all ``mongos`` servers. It also monitors its
+network latency to each server.
+
+PyMongo distributes operations evenly among the set of ``mongos`` servers within its
+``localThresholdMS`` (similar to how it distributes reads to secondaries
+in a replica set). By default, the threshold is 15 ms.
+
+The server with the lowest latency, and all servers with latencies no more than
+``localThresholdMS`` beyond the server with the lowest latency, receive
+operations equally. For example, consider the following three ``mongos`` servers:
+
+- host1: 20 ms
+- host2: 35 ms
+- host3: 40 ms
+
+By default, the ``localThresholdMS`` is 15 ms, so PyMongo uses "host1" and "host2"
+evenly. It uses "host1" because its network latency to the driver is shortest. It
+uses "host2" because its latency is within 15 ms of the server with the lowest latency.
+PyMongo doesn't use "host3" because its latency is 20 ms beyond the server with the
+lowest latency.
+
+To ensure that all servers are within the threshold, set ``localThresholdMS`` to 30
+ms as shown in the following example:
+
+.. code-block:: python
+
+   >> client = MongoClient('mongodb://host1,host2,host3/?localThresholdMS=30')
+
+.. warning:: 
+  
+   Do **not** connect PyMongo to a pool of ``mongos`` instances through a
+   load balancer. A single socket connection must always route to the same
+   ``mongos`` instance for proper cursor support.

source/connect/connection-options.txt

@@ -0,0 +1,112 @@
+.. _pymongo-network-compression:
+
+========================
+Compress Network Traffic
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: zlib, zstandard, zstd, snappy
+
+Overview
+--------
+
+{+driver-short+} provides a connection option to compress messages, which reduces the amount
+of data passed over the network between MongoDB and your application.
+
+{+driver-short+} supports the following compression algorithms.
+
+1. `Snappy <https://google.github.io/snappy/>`__: Available in MongoDB 3.6 and later. This
+   option requires the `python-snappy <https://pypi.org/project/python-snappy/>`__ package.
+
+2. `Zlib <https://zlib.net/>`__: Available in MongoDB 3.6 and later. This option requires
+   the zlib module, included in the standard library in Python v1.5 and later.
+
+3. `Zstandard <https://github.com/facebook/zstd/>`__: Available in MongoDB 4.2 and later.
+   This option requires the `zstandard <https://pypi.org/project/zstandard/>`__ package.
+
+If you don't specify a compression algorithm, {+driver-short+} doesn't compress your
+network traffic. If you specify multiple compression algorithms, the driver selects the
+first one in the list supported by your MongoDB instance.
+
+.. _pymongo-enable-compression:
+
+Specify Compression Algorithms
+------------------------------
+
+To enable compression for the connection to your MongoDB instance, use the
+``compressors`` connection option and specify the compression algorithms you want to use.
+You can do this in two ways: 
+
+- Pass the algorithms as an argument to the ``MongoClient`` constructor.
+- Specify the algorithms in your connection string.
+
+The following code example shows both options:
+
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: python
+         :emphasize-lines: 2
+
+         client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname@:<port>",
+                                      compressors = "snappy,zstd,zlib")
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: python
+         :emphasize-lines: 2
+
+         uri = ("mongodb://<username>:<password>@<hostname>:<port>/?"
+                "compressors=snappy,zstd,zlib")
+         client = pymongo.MongoClient(uri)
+
+Set the zlib Compression Level
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you specify ``zlib`` as one of your compression algorithms, you can also use the
+``zlibCompressionLevel`` option to specify a compression level. This option accepts
+an integer value between ``-1`` and ``9``:
+
+- **-1:** (Default). zlib uses its default compression level (usually ``6``).
+- **0:** No compression.
+- **1:** Fastest speed but lowest compression.
+- **9:** Best compression but slowest speed.
+
+The following code example specifies the ``zlib`` compression algorithm and a value of
+``1`` for the ``zlibCompressionLevel`` option:
+
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: python
+         :emphasize-lines: 2-3
+
+         client = pymongo.MongoClient("mongodb://<username>:<password>@<hostname@:<port>",
+                                      compressors = "zlib",
+                                      zlibCompressionLevel=1)
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: python
+         :emphasize-lines: 2-3
+
+         uri = ("mongodb://<username>:<password>@<hostname>:<port>/?"
+                "compressors=zlib"
+                "zlibCompressionLevel=1")
+         client = pymongo.MongoClient(uri)