PYTHON-1338 Update change stream documentation.

Author: ShaneHarvey

pymongo/change_stream.py

@@ -26,29 +26,8 @@ class ChangeStream(object):
     Should not be called directly by application developers. Use
     :meth:`~pymongo.collection.Collection.watch` instead.
 
-    :Parameters:
-      - `collection`: The watched :class:`~pymongo.collection.Collection`.
-      - `pipeline`: A list of aggregation pipeline stages to append to an
-        initial `$changeStream` aggregation stage.
-      - `full_document` (string): The fullDocument to pass as an option
-        to the $changeStream pipeline stage. Allowed values: 'default',
-        'updateLookup'. When set to 'updateLookup', the change notification
-        for partial updates will include both a delta describing the
-        changes to the document, as well as a copy of the entire document
-        that was changed from some time after the change occurred.
-      - `resume_after` (optional): The logical starting point for this
-        change stream.
-      - `max_await_time_ms` (optional): The maximum time in milliseconds
-        for the server to wait for changes before responding to a getMore
-        operation.
-      - `batch_size` (optional): The maximum number of documents to return
-        per batch.
-      - `collation` (optional): The :class:`~pymongo.collation.Collation`
-        to use for the aggregation.
-      - `session` (optional): a
-        :class:`~pymongo.client_session.ClientSession`.
-
     .. versionadded: 3.6
+    .. mongodoc:: changeStreams
     """
     def __init__(self, collection, pipeline, full_document,
                  resume_after=None, max_await_time_ms=None, batch_size=None,

pymongo/collection.py

@@ -2215,22 +2215,23 @@ def watch(self, pipeline=None, full_document='default', resume_after=None,
               session=None):
         """Watch changes on this collection.
 
-        Performs an aggregation with an implicit initial
-        `$changeStream aggregation stage`_ and returns a
-        :class:`~pymongo.change_stream.ChangeStream` cursor that iterates over
-        changes on this collection. Introduced in MongoDB 3.6.
+        Performs an aggregation with an implicit initial ``$changeStream``
+        stage and returns a :class:`~pymongo.change_stream.ChangeStream`
+        cursor which iterates over changes on this collection.
+        Introduced in MongoDB 3.6.
 
         .. code-block:: python
 
            for change in db.collection.watch():
                print(change)
 
-        The ChangeStream returned automatically resumes when it
-        encounters a potentially recoverable error during iteration. The resume
-        process is transparent to the application and ensures no change stream
-        documents are lost; the call to
-        :meth:`~pymongo.change_stream.ChangeStream.next` blocks until the next
-        change document is returned or an unrecoverable error is raised.
+        The :class:`~pymongo.change_stream.ChangeStream` iterable blocks
+        until the next change document is returned or an error is raised. If
+        the :meth:`~pymongo.change_stream.ChangeStream.next` method encounters
+        a network error when retrieving a batch from the server, it will
+        automatically attempt to recreate the cursor such that no change
+        events are missed. Any error encountered during the resume attempt
+        indicates there may be an outage and will be raised.
 
         .. code-block:: python
 
@@ -2239,29 +2240,29 @@ def watch(self, pipeline=None, full_document='default', resume_after=None,
                         [{'$match': {'operationType': 'insert'}}]):
                     print(insert_change)
             except pymongo.errors.PyMongoError:
-                # We know for sure it's unrecoverable:
+                # The ChangeStream encountered an unrecoverable error or the
+                # resume attempt failed to recreate the cursor.
                 log.error('...')
 
         For a precise description of the resume process see the
-        `Change Streams specification`_.
+        `change streams specification`_.
 
         .. note:: Using this helper method is preferred to directly calling
             :meth:`~pymongo.collection.Collection.aggregate` with a
-            ``$changeStream`` aggregation stage, for the purpose of supporting
+            ``$changeStream`` stage, for the purpose of supporting
             resumability.
 
         .. warning:: This Collection's :attr:`read_concern` must be
             ``ReadConcern("majority")`` in order to use the ``$changeStream``
-            aggregation stage.
+            stage.
 
         :Parameters:
           - `pipeline` (optional): A list of aggregation pipeline stages to
-            append to an initial `$changeStream` aggregation stage. Not all
-            pipeline stages are valid after a `$changeStream` stage, see the
-            `$changeStream aggregation stage`_ documentation for the supported
-            stages.
+            append to an initial ``$changeStream`` stage. Not all
+            pipeline stages are valid after a ``$changeStream`` stage, see the
+            MongoDB documentation on change streams for the supported stages.
           - `full_document` (optional): The fullDocument to pass as an option
-            to the $changeStream pipeline stage. Allowed values: 'default',
+            to the ``$changeStream`` stage. Allowed values: 'default',
             'updateLookup'.  Defaults to 'default'.
             When set to 'updateLookup', the change notification for partial
             updates will include both a delta describing the changes to the
@@ -2284,10 +2285,9 @@ def watch(self, pipeline=None, full_document='default', resume_after=None,
 
         .. versionadded:: 3.6
 
-        .. _$changeStream aggregation stage:
-            https://docs.mongodb.com/manual/reference/operator/aggregation/changeStream/
+        .. mongodoc:: changeStreams
 
-        .. _Change Streams specification:
+        .. _change streams specification:
             https://github.com/mongodb/specifications/blob/master/source/change-streams.rst
         """
         if pipeline is None: