DOCSP-36997 - Collation (#27)

Co-authored-by: Jordan Smith <[email protected]>

Author: mongoKart

source/fundamentals.txt

@@ -13,6 +13,7 @@ Fundamentals
 
    /fundamentals/authentication
    /fundamentals/csot
+   /fundamentals/collations
    /fundamentals/databases-and-collections
    /fundamentals/dates-and-times
    /fundamentals/enterprise-authentication
@@ -24,6 +25,7 @@ Fundamentals
 
 - :ref:`pymongo-auth`
 - :ref:`pymongo-csot`
+- :ref:`pymongo-collations`
 - :ref:`pymongo-databases-collections`
 - :ref:`pymongo-dates-times`
 - :ref:`pymongo-enterprise-auth`

source/fundamentals/collations.txt

@@ -1,62 +1,66 @@
-.. uses collations.rst
+.. _pymongo-collations:
 
 Collations
 ==========
 
-.. seealso:: The API docs for ``~pymongo.collation``.
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
 
-Collations are a new feature in MongoDB version 3.4. They provide a set of rules
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: order, sort, translation, accent, diacritic, compare
+
+Collations provide a set of rules
 to use when comparing strings that comply with the conventions of a particular
 language, such as Spanish or German. If no collation is specified, the server
-sorts strings based on a binary comparison. Many languages have specific
+sorts strings based on a binary comparison. However, many languages have specific
 ordering rules, and collations allow users to build applications that adhere to
-language-specific comparison rules.
+these rules.
 
 In French, for example, the last accent in a given word determines the sorting
-order. The correct sorting order for the following four words in French is:
+order. The following example shows the correct sorting order for four words in French:
 
-.. code-block:: python
+.. code-block:: none
 
-  cote < côte < coté < côté
+   cote < côte < coté < côté
 
 Specifying a French collation allows users to sort string fields using the
 French sort order.
 
 Usage
 -----
 
-Users can specify a collation for a
-:ref:`collection<collation-on-collection>`, an
-:ref:`index<collation-on-index>`, or a
-:ref:`CRUD command <collation-on-operation>`.
+You can specify a collation for a :ref:`collection <collation-on-collection>`, an
+:ref:`index<collation-on-index>`, or a :ref:`CRUD command <collation-on-operation>`.
 
 Collation Parameters:
 ~~~~~~~~~~~~~~~~~~~~~
 
-Collations can be specified with the ``~pymongo.collation.Collation`` model
-or with plain Python dictionaries. The structure is the same:
+You can specify a collation by using the ``~pymongo.collation.Collation`` model
+or Python dictionaries. In either case, the structure is the same:
 
 .. code-block:: python
 
-   Collation(locale=<string>,
-             caseLevel=<bool>,
-             caseFirst=<string>,
-             strength=<int>,
-             numericOrdering=<bool>,
-             alternate=<string>,
-             maxVariable=<string>,
-             backwards=<bool>)
+    Collation(locale=<string>,
+              caseLevel=<bool>,
+              caseFirst=<string>,
+              strength=<int>,
+              numericOrdering=<bool>,
+              alternate=<string>,
+              maxVariable=<string>,
+              backwards=<bool>)
 
 The only required parameter is ``locale``, which the server parses as
-an `ICU format locale ID <https://www.mongodb.com/docs/manual/reference/collation-locales-defaults/>`_.
+an `ICU format locale ID <https://www.mongodb.com/docs/manual/reference/collation-locales-defaults/>`__.
 For example, set ``locale`` to ``en_US`` to represent US English
 or ``fr_CA`` to represent Canadian French.
 
-For a complete description of the available parameters, see the MongoDB `manual
-</>`_.
-
-.. COMMENT add link for manual entry.
-
 .. _collation-on-collection:
 
 Assign a Default Collation to a Collection
@@ -66,16 +70,16 @@ The following example demonstrates how to create a new collection called
 ``contacts`` and assign a default collation with the ``fr_CA`` locale. This
 operation ensures that all queries that are run against the ``contacts``
 collection use the ``fr_CA`` collation unless another collation is explicitly
-specified:
+specified.
 
 .. code-block:: python
 
-  from pymongo import MongoClient
-  from pymongo.collation import Collation
+   from pymongo import MongoClient
+   from pymongo.collation import Collation
 
-  db = MongoClient().test
-  collection = db.create_collection('contacts',
-                                    collation=Collation(locale='fr_CA'))
+   db = MongoClient().test
+   collection = db.create_collection('contacts',
+                                     collation=Collation(locale='fr_CA'))
 
 .. _collation-on-index:
 
@@ -86,63 +90,60 @@ When creating a new index, you can specify a default collation.
 
 The following example shows how to create an index on the ``name``
 field of the ``contacts`` collection, with the ``unique`` parameter
-enabled and a default collation with ``locale`` set to ``fr_CA``:
+enabled and a default collation with ``locale`` set to ``fr_CA``.
 
 .. code-block:: python
 
-  from pymongo import MongoClient
-  from pymongo.collation import Collation
+   from pymongo import MongoClient
+   from pymongo.collation import Collation
 
-  contacts = MongoClient().test.contacts
-  contacts.create_index('name',
-                        unique=True,
-                        collation=Collation(locale='fr_CA'))
+   contacts = MongoClient().test.contacts
+   contacts.create_index('name',
+                         unique=True,
+                         collation=Collation(locale='fr_CA'))
 
 .. _collation-on-operation:
 
 Specify a Collation for a Query
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Individual queries can specify a collation to use when sorting
+A query can specify a collation to use when sorting
 results. The following example demonstrates a query that runs on the
-``contacts`` collection in database ``test``. It matches on
+``contacts`` collection in the ``test`` database. It matches on
 documents that contain ``New York`` in the ``city`` field,
-and sorts on the ``name`` field with the ``fr_CA`` collation:
+and sorts on the ``name`` field with the ``fr_CA`` collation.
 
 .. code-block:: python
 
-  from pymongo import MongoClient
-  from pymongo.collation import Collation
+   from pymongo import MongoClient
+   from pymongo.collation import Collation
 
-  collection = MongoClient().test.contacts
-  docs = collection.find({'city': 'New York'}).sort('name').collation(
-      Collation(locale='fr_CA'))
+   collection = MongoClient().test.contacts
+   docs = collection.find({'city': 'New York'}).sort('name').collation(
+       Collation(locale='fr_CA'))
 
 Other Query Types
 ~~~~~~~~~~~~~~~~~
 
-You can use collations to control document matching rules for several different
-types of queries. All the various update and delete methods
-(the ``~pymongo.collection.Collection.update_one`` method,
-the ``~pymongo.collection.Collection.update_many`` method,
-the ``~pymongo.collection.Collection.delete_one`` method, etc.) support collation, and
-you can create query filters which employ collations to comply with any of the
+You can use collations to control document-matching rules for several different
+types of queries. All methods that perform update or delete operations support collation,
+and you can create query filters that use collations to comply with any of the
 languages and variants available to the ``locale`` parameter.
 
 The following example uses a collation with ``strength`` set to
 ``~pymongo.collation.CollationStrength.SECONDARY``, which considers only
-the base character and character accents in string comparisons, but not case
-sensitivity, for example. All documents in the ``contacts`` collection with
-``jürgen`` (case-insensitive) in the ``first_name`` field are updated:
+the base character and character accents in string comparisons, but not case-sensitivity,
+for example. All documents in the ``contacts`` collection with
+``jürgen`` (case-insensitive) in the ``first_name`` field are updated.
 
 .. code-block:: python
 
-  from pymongo import MongoClient
-  from pymongo.collation import Collation, CollationStrength
+   from pymongo import MongoClient
+   from pymongo.collation import Collation, CollationStrength
 
-  contacts = MongoClient().test.contacts
-  result = contacts.update_many(
-      {'first_name': 'jürgen'},
-      {'$set': {'verified': 1}},
-      collation=Collation(locale='de',
-                          strength=CollationStrength.SECONDARY))
+   contacts = MongoClient().test.contacts
+   result = contacts.update_many(
+       {'first_name': 'jürgen'},
+       {'$set': {'verified': 1}},
+       collation=Collation(locale='de',
+                           strength=CollationStrength.SECONDARY))