PYTHON-2726 Document read preference quirks

(cherry picked from commit a94504b)

Author: behackett

doc/mongo_extensions.py

@@ -75,7 +75,7 @@ def process_mongodoc_nodes(app, doctree, fromdocname):
                 anchor = name["ids"][0]
                 break
         for para in node.traverse(nodes.paragraph):
-            tag = str(para.traverse()[1])
+            tag = str(list(para.traverse())[1])
             link = mongoref("", "")
             link["refuri"] = "http://dochub.mongodb.org/core/%s" % tag
             link["name"] = anchor

pymongo/errors.py

@@ -116,7 +116,7 @@ class NotMasterError(AutoReconnect):
     Use :exc:`~pymongo.errors.NotPrimaryError` instead.
 
     .. versionchanged:: 3.12
-    Deprecated. Use :exc:`~pymongo.errors.NotPrimaryError` instead.
+      Deprecated. Use :exc:`~pymongo.errors.NotPrimaryError` instead.
     """
     def __init__(self, message='', errors=None):
         super(NotMasterError, self).__init__(

pymongo/read_preferences.py

@@ -268,6 +268,10 @@ class PrimaryPreferred(_ServerMode):
     * When connected to a replica set queries are sent to the primary if
       available, otherwise a secondary.
 
+    .. note:: When a :class:`~pymongo.mongo_client.MongoClient` is first
+      created reads will be routed to an available secondary until the
+      primary of the replica set is discovered.
+
     :Parameters:
       - `tag_sets`: The :attr:`~tag_sets` to use if the primary is not
         available.
@@ -346,6 +350,10 @@ class SecondaryPreferred(_ServerMode):
     * When connected to a replica set queries are distributed among
       secondaries, or the primary if no secondary is available.
 
+    .. note:: When a :class:`~pymongo.mongo_client.MongoClient` is first
+      created reads will be routed to the primary of the replica set until
+      an available secondary is discovered.
+
     :Parameters:
       - `tag_sets`: The :attr:`~tag_sets` for this read preference.
       - `max_staleness`: (integer, in seconds) The maximum estimated