DOCSP-48207-404s (#203)

(cherry picked from commit e10923b)

Author: rustagir

examples/src/test/kotlin/RetrieveDataTest.kt

@@ -28,7 +28,7 @@ internal class RetrieveDataTest {
         private val config = getConfig()
         private val client = MongoClient.create(config.connectionUri)
         private val database = client.getDatabase("retrieve_data")
-        val collection = database.getCollection<PaintOrder>("paint_order")
+        val collection = database.getCollection<PaintOrder>("orders")
 
         @BeforeAll
         @JvmStatic

source/fundamentals/aggregation.txt

@@ -1,3 +1,5 @@
+.. _kotlin-aggregation:
+
 ===========
 Aggregation
 ===========
@@ -11,8 +13,6 @@ Aggregation
 Overview
 --------
 
-.. _kotlin-aggregation:
-
 In this guide, you can learn how to use **aggregation operations** in the MongoDB Kotlin driver.
 
 Aggregation operations process data in your MongoDB collections and return computed results. MongoDB's Aggregation

source/fundamentals/crud/query-document.txt

@@ -1,3 +1,5 @@
+.. _kotlin-fundamentals-query:
+
 ===============
 Specify a Query
 ===============

source/fundamentals/crud/read-operations/geo.txt

@@ -1,7 +1,16 @@
+.. _kotlin-fundamentals-geospatial-search:
+
 ===================
 Search Geospatially
 ===================
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, coordinates, plane, earth
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -11,8 +20,9 @@ Search Geospatially
 Overview
 --------
 
-In this guide, you can learn how to search **geospatial data** with the
-MongoDB Kotlin Driver, and the different geospatial data formats supported by MongoDB.
+In this guide, you can learn how to query **geospatial data** by using
+the {+driver-short+}. You can also learn about different geospatial data
+formats supported by MongoDB.
 
 Geospatial data is data that represents a geographical location on
 the surface of the Earth. Examples of geospatial data include:
@@ -32,7 +42,7 @@ Here is the location of MongoDB headquarters in GeoJSON:
 
 .. code-block:: json
 
-   "MongoDB Headquarters" : {
+   "location" : {
       "type": "point",
       "coordinates": [-73.986805, 40.7620853]
    }
@@ -43,7 +53,7 @@ For definitive information on GeoJSON, see the
 GeoJSON Positions
 ~~~~~~~~~~~~~~~~~
 
-A position represents a single place on Earth, and exists in code as an array
+A position represents a single place on Earth and is given as an array
 containing two or three number values: 
 
 - Longitude in the first position (required)
@@ -52,11 +62,11 @@ containing two or three number values:
 
 .. important:: Longitude then Latitude
 
-  GeoJSON orders coordinates as longitude first and latitude second. This may
-  be surprising as geographic coordinate system conventions generally list
-  latitude first and longitude second. Make sure to check what format any other
-  tools you are working with use. Popular tools such as OpenStreetMap and Google
-  Maps list coordinates as latitude first and longitude second.
+   GeoJSON orders coordinates as longitude first and latitude second. This may
+   be surprising as geographic coordinate system conventions generally list
+   latitude first and longitude second. Make sure to check what format any other
+   tools you are working with use. Popular tools such as OpenStreetMap and Google
+   Maps list coordinates as latitude first and longitude second.
 
 GeoJSON Types
 ~~~~~~~~~~~~~
@@ -66,70 +76,73 @@ made up of positions.
 
 Here are some common GeoJSON types and how you can specify them with positions:
 
-- ``Point``: a single position. This could represent the location of a
-  `sculpture <https://en.wikipedia.org/wiki/Chicago_Picasso>`__. 
-- ``LineString``: an array of two or more positions, thus forming a series of line
+- ``Point``: Single position. This could represent the location of a
+  `sculpture <https://en.wikipedia.org/wiki/Chicago_Picasso>`__.
+- ``LineString``: Array of two or more positions, thus forming a series of line
   segments. This could represent
   `the route of the Great Wall of China <https://commons.wikimedia.org/wiki/File:GreatWallChina4.png>`__. 
-- ``Polygon``: an array of positions in which the first and last
-  position are the same, thus enclosing some space. This could represent 
+- ``Polygon``: Array of positions in which the first and last
+  position are the same, enclosing some space. This could represent 
   `the land within Vatican City <https://commons.wikimedia.org/wiki/File:Vatican_City_map_EN.png>`__.
 
-
-To learn more about the shapes you can use in MongoDB, see the
-:manual:`GeoJSON manual entry </reference/geojson/>`.
+To learn more about the shapes you can use in MongoDB, see
+:manual:`GeoJSON </reference/geojson/>` in the Server manual.
 
 Index
 ~~~~~
 
 To query data stored in the GeoJSON format, add the field containing
 GeoJSON data to a ``2dsphere`` index. The following snippet creates a
-``2dsphere`` index on the ``location.geo`` field using the ``Indexes`` builder:
+``2dsphere`` index on the ``location.geo`` field by using the
+``Indexes`` builder:
 
 .. literalinclude:: /examples/generated/GeoTest.snippet.geo2dsphere-index.kt
    :language: kotlin
 
-For more information on the ``Indexes`` builder, see our 
-:doc:`guide on the Indexes builder </fundamentals/builders/indexes>`.
+To learn more about the ``Indexes`` builder, see the 
+:ref:`indexes-builders` guide.
 
 Coordinates on a 2D Plane
 -------------------------
 
 You can store geospatial data using ``x`` and ``y`` coordinates on 
 a two-dimensional Euclidean plane. We refer to coordinates on a two-dimensional
-plane as "legacy coordinate pairs".
+plane as *legacy coordinate pairs*.
 
 Legacy coordinate pairs have the following structure:
 
 .. code-block:: json
 
-   "<field name>" : [ x, y ]
+   { "location" : [ x, y ] }
 
-Your field should contain an array of two values in which the first represents 
+The field value contains an array of two values in which the first represents 
 the ``x`` axis value and the second represents the ``y`` axis value.
 
 Index
 ~~~~~
 
 To query data stored as legacy coordinate pairs, you must add the field containing
 legacy coordinate pairs to  a ``2d`` index. The following snippet creates a
-``2d`` index on the ``coordinates`` field using the ``Indexes`` builder:
+``2d`` index on the ``coordinates`` field by using the ``Indexes`` builder:
 
 .. literalinclude:: /examples/generated/GeoTest.snippet.geo2d-index.kt
    :language: kotlin
 
-For more information on the ``Indexes`` builder, see our 
-:doc:`guide on the Indexes builder </fundamentals/builders/indexes>`. 
+To learn more about the ``Indexes`` builder, see the 
+:ref:`indexes-builders` guide.
 
 For more information on legacy coordinate pairs, see the
-:manual:`MongoDB server manual page on legacy coordinate pairs </geospatial-queries/#legacy-coordinate-pairs>`.
+:manual:`Legacy Coordinate Pairs
+</geospatial-queries/#legacy-coordinate-pairs>` section of the
+Geospatial Queries guide in the Server manual.
 
 .. tip:: Supported Operators
 
    Spherical (``2dsphere``) and flat (``2d``) indexes support some, but
-   not all, of the same query operators. For a full list of operators
-   and their index compatibility, see the
-   :manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
+   not all, of the same query operators. To view a full list of operators
+   and their index compatibility, see the :manual:`Geospatial Query
+   Operators </geospatial-queries/#geospatial-query-operators>` section
+   of the Geospatial Queries guide in the Server manual.
 
 Geospatial Queries
 ------------------
@@ -151,58 +164,56 @@ You can specify these query operators in the MongoDB Kotlin driver with the
 ``near()``, ``geoWithin()``, ``nearSphere()``, and ``geoIntersects()`` utility
 methods of the ``Filters`` builder class.
 
-For more information on geospatial query operators, see the
-:manual:`manual entry for geospatial queries </geospatial-queries/#geospatial-query-operators>`.
+To learn more about geospatial query operators, see the :manual:`Geospatial Query
+Operators </geospatial-queries/#geospatial-query-operators>` section
+of the Geospatial Queries guide in the Server manual.
 
-For more information on ``Filters``, see our 
-:doc:`guide on the Filters builder </fundamentals/builders/filters>`.  
+To learn more about the ``Filters`` builder, see the 
+:ref:`filters-builders` guide.  
 
 Query Parameters
 ~~~~~~~~~~~~~~~~
 
-To specify a shape to use in a geospatial query, use the
-``Position``, ``Point``, ``LineString``, and ``Polygon`` classes of the MongoDB
-Kotlin driver.
+To specify a shape to use in a geospatial query, use the ``Position``,
+``Point``, ``LineString``, and ``Polygon`` classes from the {+driver-short+}.
 
-For a full list of the GeoJSON shapes available in the MongoDB Kotlin driver, see the
-`GeoJSON package
-<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`__
+To learn more about the GeoJSON shape classes, see the
+`GeoJSON package <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`__
 API Documentation.
 
-Examples
---------
+Geospatial Query Examples
+-------------------------
 
 The following examples use the MongoDB Atlas sample dataset. You can learn how
 to  set up your own free-tier Atlas cluster and how to load the sample dataset
-in our :doc:`quick start guide </quick-start>`.
+in the :ref:`kotlin-quickstart` guide.
 
 The examples use the ``theaters`` collection in the ``sample_mflix`` database
 from the sample dataset. 
 
-The examples require the following imports:
+The examples in this section require the following imports:
 
-.. code-block:: 
-  :source: kotlin
+.. code-block:: kotlin
 
-  import com.mongodb.client.model.geojson.Point
-  import com.mongodb.client.model.geojson.Polygon
-  import com.mongodb.client.model.geojson.Position
-  import com.mongodb.client.model.Filters.near
-  import com.mongodb.client.model.Filters.geoWithin
-  import com.mongodb.client.model.Projections.fields
-  import com.mongodb.client.model.Projections.include
-  import com.mongodb.client.model.Projections.excludeId
+   import com.mongodb.client.model.geojson.Point
+   import com.mongodb.client.model.geojson.Polygon
+   import com.mongodb.client.model.geojson.Position
+   import com.mongodb.client.model.Filters.near
+   import com.mongodb.client.model.Filters.geoWithin
+   import com.mongodb.client.model.Projections.fields
+   import com.mongodb.client.model.Projections.include
+   import com.mongodb.client.model.Projections.excludeId
 
-The data is modeled using the following Kotlin data class:
+The sample documents are modeled by the following {+language+} data class:
 
 .. literalinclude:: /examples/generated/GeoTest.snippet.theater-data-class.kt
-  :language: kotlin
+   :language: kotlin
 
-The results are modeled using the following Kotlin data class:
+The result documents are modeled by the following {+language+} data class:
 
 .. literalinclude:: /examples/generated/GeoTest.snippet.results-data-class.kt
-  :language: kotlin
-  
+   :language: kotlin
+
 The ``theaters`` collection already contains a ``2dsphere`` index on the 
 ``"${Theater::location.name}.${Theater.Location::geo.name}"`` field.
 
@@ -213,8 +224,8 @@ To search for and return documents from nearest to farthest from a point, use
 the ``near()`` static utility method of the ``Filters`` builder class. The
 ``near()`` method constructs a query with the ``$near`` query operator. 
 
-The following example queries for theaters between ``10,000`` and ``5,000``
-meters from the Great Lawn of Central Park:
+The following example queries for movie theaters between ``10000`` and
+``5000`` meters from the Great Lawn of Central Park:
 
 .. io-code-block::
 
@@ -237,17 +248,14 @@ meters from the Great Lawn of Central Park:
       TheaterResults(location=Location(address=Address(city=Flushing)))
       TheaterResults(location=Location(address=Address(city=Elmhurst)))
 
-.. tip:: Fun Fact
+.. tip::
 
-   MongoDB uses the
-   :manual:`same reference system </reference/glossary/#std-term-WGS84>`
+   MongoDB uses the :manual:`same reference system </reference/glossary/#std-term-WGS84>`
    as GPS satellites to calculate geometries over the Earth.
 
-For more information on the ``$near`` operator, see the 
-:manual:`reference documentation for $near </reference/operator/query/near/#mongodb-query-op.-near>`.
-
-For more information on ``Filters``, see
-:doc:`our guide on the Filters builder </fundamentals/builders/filters>`.
+To learn more about the ``$near`` operator, see the 
+:manual:`$near </reference/operator/query/near/>` reference in the
+Server manual.
 
 Query Within a Range
 ~~~~~~~~~~~~~~~~~~~~
@@ -276,13 +284,11 @@ The following example searches for movie theaters in a section of Long Island.
 
 The following figure shows the polygon defined by the
 ``longIslandTriangle`` variable and dots representing the locations of
-the movie theaters returned by our query. 
+the movie theaters returned by our query.
 
 .. figure:: /includes/figures/geo_geometry.png
-   :alt: Area of Long Island we are searching for movie theaters
-
-For more information on the ``$geoWithin`` operator, see the
-:manual:`reference documentation for $geoWithin </reference/operator/query/geoWithin/>`
+   :alt: Area of Long Island in which to search for movie theaters
 
-For more information on the operators you can use in your query, see the
-:manual:`MongoDB server manual page on geospatial query operators </geospatial-queries/index.html>`
+To learn more about the ``$geoWithin`` operator, see the
+:manual:`$geoWithin </reference/operator/query/geoWithin/>` reference in
+the Server manual.