PYTHON-2870 Remove problematic mongodoc sphinx extension and add support for man/text/latex/etc.. docs output

Author: ShaneHarvey

bson/dbref.py

@@ -42,7 +42,7 @@ def __init__(self, collection, id, database=None, _extra={}, **kwargs):
           - `**kwargs` (optional): additional keyword arguments will
             create additional, custom fields
 
-        .. mongodoc:: dbrefs
+        .. seealso:: The MongoDB documentation on `dbrefs <https://dochub.mongodb.org/core/dbrefs>`_.
         """
         if not isinstance(collection, str):
             raise TypeError("collection must be an instance of str")

bson/objectid.py

@@ -89,7 +89,7 @@ def __init__(self, oid=None):
         :Parameters:
           - `oid` (optional): a valid ObjectId.
 
-        .. mongodoc:: objectids
+        .. seealso:: The MongoDB documentation on `ObjectIds`_.
 
         .. versionchanged:: 3.8
            :class:`~bson.objectid.ObjectId` now implements the `ObjectID

doc/conf.py

@@ -14,8 +14,7 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage',
-              'sphinx.ext.todo', 'doc.mongo_extensions',
-              'sphinx.ext.intersphinx']
+              'sphinx.ext.todo', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/examples/encryption.rst

@@ -16,7 +16,7 @@ level encryption supports workloads where applications must guarantee that
 unauthorized parties, including server administrators, cannot read the
 encrypted data.
 
-.. mongodoc:: client-side-field-level-encryption
+.. seealso:: The MongoDB documentation on `Client Side Field Level Encryption <https://dochub.mongodb.org/core/client-side-field-level-encryption>`_.
 
 Dependencies
 ------------

doc/examples/geo.rst

@@ -10,7 +10,7 @@ Geospatial Indexing Example
 This example shows how to create and use a :data:`~pymongo.GEO2D`
 index in PyMongo. To create a spherical (earth-like) geospatial index use :data:`~pymongo.GEOSPHERE` instead.
 
-.. mongodoc:: geo
+.. seealso:: The MongoDB documentation on `Geospatial Indexes <https://dochub.mongodb.org/core/geo>`_.
 
 Creating a Geospatial Index
 ---------------------------

doc/examples/high_availability.rst

@@ -14,7 +14,7 @@ PyMongo makes working with `replica sets
 replica set and show how to handle both initialization and normal
 connections with PyMongo.
 
-.. mongodoc:: rs
+.. seealso:: The MongoDB documentation on `replication <https://dochub.mongodb.org/core/rs>`_.
 
 Starting a Replica Set
 ~~~~~~~~~~~~~~~~~~~~~~

doc/mongo_extensions.py

@@ -17,7 +17,7 @@
 The :mod:`gridfs` package is an implementation of GridFS on top of
 :mod:`pymongo`, exposing a file-like interface.
 
-.. mongodoc:: gridfs
+.. seealso:: The MongoDB documentation on `gridfs <https://dochub.mongodb.org/core/gridfs>`_.
 """
 
 from collections import abc
@@ -63,7 +63,7 @@ def __init__(self, database, collection="fs", disable_md5=False):
            `database` must use an acknowledged
            :attr:`~pymongo.database.Database.write_concern`
 
-        .. mongodoc:: gridfs
+        .. seealso:: The MongoDB documentation on `gridfs <https://dochub.mongodb.org/core/gridfs>`_.
         """
         if not isinstance(database, Database):
             raise TypeError("database must be an instance of Database")
@@ -367,7 +367,7 @@ def find(self, *args, **kwargs):
            Removed the read_preference, tag_sets, and
            secondary_acceptable_latency_ms options.
         .. versionadded:: 2.7
-        .. mongodoc:: find
+        .. seealso:: The MongoDB documentation on `find <https://dochub.mongodb.org/core/find>`_.
         """
         return GridOutCursor(self.__collection, *args, **kwargs)
 
@@ -452,7 +452,7 @@ def __init__(self, db, bucket_name="fs",
 
         .. versionadded:: 3.1
 
-        .. mongodoc:: gridfs
+        .. seealso:: The MongoDB documentation on `gridfs <https://dochub.mongodb.org/core/gridfs>`_.
         """
         if not isinstance(db, Database):
             raise TypeError("database must be an instance of Database")

gridfs/__init__.py

@@ -816,7 +816,7 @@ def __init__(self, collection, filter=None, skip=0, limit=0,
 
         .. versionadded 2.7
 
-        .. mongodoc:: cursors
+        .. seealso:: The MongoDB documentation on `cursors <https://dochub.mongodb.org/core/cursors>`_.
         """
         _disallow_transactions(session)
         collection = _clear_entity_type_registry(collection)

gridfs/grid_file.py

@@ -64,7 +64,7 @@ class ChangeStream(object):
     :meth:`pymongo.mongo_client.MongoClient.watch` instead.
 
     .. versionadded:: 3.6
-    .. mongodoc:: changeStreams
+    .. seealso:: The MongoDB documentation on `changeStreams <https://dochub.mongodb.org/core/changeStreams>`_.
     """
     def __init__(self, target, pipeline, full_document, resume_after,
                  max_await_time_ms, batch_size, collation,

pymongo/change_stream.py

@@ -37,7 +37,7 @@
 causally consistent session, an application can read its own writes and is
 guaranteed monotonic reads, even when reading from replica set secondaries.
 
-.. mongodoc:: causal-consistency
+.. seealso:: The MongoDB documentation on `causal-consistency <https://dochub.mongodb.org/core/causal-consistency>`_.
 
 .. _transactions-ref:
 
@@ -91,7 +91,7 @@
 are routed to the same mongos server. When the transaction is completed, by
 running either commitTransaction or abortTransaction, the session is unpinned.
 
-.. mongodoc:: transactions
+.. seealso:: The MongoDB documentation on `transactions <https://dochub.mongodb.org/core/transactions>`_.
 
 .. _snapshot-reads-ref:
 

pymongo/client_session.py

@@ -138,7 +138,7 @@ def __init__(self, database, name, create=False, codec_options=None,
 
                collection.__my_collection__
 
-        .. mongodoc:: collections
+        .. seealso:: The MongoDB documentation on `collections <https://dochub.mongodb.org/core/collections>`_.
         """
         super(Collection, self).__init__(
             codec_options or database.codec_options,
@@ -1376,8 +1376,7 @@ def find(self, *args, **kwargs):
            expression object.
            Soft deprecated the ``manipulate`` option.
 
-        .. mongodoc:: find
-
+        .. seealso:: The MongoDB documentation on `find <https://dochub.mongodb.org/core/find>`_.
         """
         return Cursor(self, *args, **kwargs)
 
@@ -1757,7 +1756,7 @@ def create_index(self, keys, session=None, **kwargs):
            :meth:`create_index` no longer caches index names. Removed support
            for the drop_dups and bucket_size aliases.
 
-        .. mongodoc:: indexes
+        .. seealso:: The MongoDB documentation on `indexes <https://dochub.mongodb.org/core/indexes>`_.
 
         .. _wildcard index: https://docs.mongodb.com/master/core/index-wildcard/#wildcard-index-core
         """
@@ -2198,7 +2197,7 @@ def watch(self, pipeline=None, full_document=None, resume_after=None,
 
         .. versionadded:: 3.6
 
-        .. mongodoc:: changeStreams
+        .. seealso:: The MongoDB documentation on `changeStreams <https://dochub.mongodb.org/core/changeStreams>`_.
 
         .. _change streams specification:
             https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.rst

pymongo/collection.py

@@ -303,7 +303,7 @@ def __init__(self, collection, cursor_info, address,
         see :meth:`~pymongo.collection.Collection.aggregate_raw_batches`
         instead.
 
-        .. mongodoc:: cursors
+        .. seealso:: The MongoDB documentation on `cursors <https://dochub.mongodb.org/core/cursors>`_.
         """
         assert not cursor_info.get('firstBatch')
         super(RawBatchCommandCursor, self).__init__(

pymongo/command_cursor.py

@@ -146,7 +146,7 @@ def __init__(self, collection, filter=None, projection=None, skip=0,
         Should not be called directly by application developers - see
         :meth:`~pymongo.collection.Collection.find` instead.
 
-        .. mongodoc:: cursors
+        .. seealso:: The MongoDB documentation on `cursors <https://dochub.mongodb.org/core/cursors>`_.
         """
         # Initialize all attributes used in __del__ before possibly raising
         # an error to avoid attribute errors during garbage collection.
@@ -494,7 +494,7 @@ def limit(self, limit):
         :Parameters:
           - `limit`: the number of results to return
 
-        .. mongodoc:: limit
+        .. seealso:: The MongoDB documentation on `limit <https://dochub.mongodb.org/core/limit>`_.
         """
         if not isinstance(limit, int):
             raise TypeError("limit must be an integer")
@@ -839,7 +839,7 @@ def explain(self):
           :meth:`~pymongo.database.Database.command` to run the explain
           command directly.
 
-        .. mongodoc:: explain
+        .. seealso:: The MongoDB documentation on `explain <https://dochub.mongodb.org/core/explain>`_.
         """
         c = self.clone()
         c.__explain = True
@@ -1233,7 +1233,7 @@ def __init__(self, *args, **kwargs):
         see :meth:`~pymongo.collection.Collection.find_raw_batches`
         instead.
 
-        .. mongodoc:: cursors
+        .. seealso:: The MongoDB documentation on `cursors <https://dochub.mongodb.org/core/cursors>`_.
         """
         super(RawBatchCursor, self).__init__(*args, **kwargs)
 
@@ -1250,7 +1250,7 @@ def _unpack_response(self, response, cursor_id, codec_options,
     def explain(self):
         """Returns an explain plan record for this cursor.
 
-        .. mongodoc:: explain
+        .. seealso:: The MongoDB documentation on `explain <https://dochub.mongodb.org/core/explain>`_.
         """
         clone = self._clone(deepcopy=True, base=Cursor(self.collection))
         return clone.explain()

pymongo/cursor.py

@@ -73,7 +73,7 @@ def __init__(self, client, name, codec_options=None, read_preference=None,
             :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
             default) client.read_concern is used.
 
-        .. mongodoc:: databases
+        .. seealso:: The MongoDB documentation on `databases <https://dochub.mongodb.org/core/databases>`_.
 
         .. versionchanged:: 3.2
            Added the read_concern option.
@@ -468,7 +468,7 @@ def watch(self, pipeline=None, full_document=None, resume_after=None,
 
         .. versionadded:: 3.7
 
-        .. mongodoc:: changeStreams
+        .. seealso:: The MongoDB documentation on `changeStreams <https://dochub.mongodb.org/core/changeStreams>`_.
 
         .. _change streams specification:
             https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.rst
@@ -585,7 +585,7 @@ def command(self, command, value=1, check=True,
            BSON regular expression to a Python regular expression object.
            Added the `codec_options` parameter.
 
-        .. mongodoc:: commands
+        .. seealso:: The MongoDB documentation on `commands <https://dochub.mongodb.org/core/commands>`_.
         """
         if read_preference is None:
             read_preference = ((session and session._txn_read_preference())

pymongo/database.py

@@ -494,7 +494,7 @@ def __init__(
             client to use Versioned API. See :ref:`versioned-api-ref` for
             details.
 
-        .. mongodoc:: connections
+        .. seealso:: The MongoDB documentation on `connections <https://dochub.mongodb.org/core/connections>`_.
 
         .. versionchanged:: 4.0
            Removed the ``waitQueueMultiple`` and ``socketKeepAlive`` keyword
@@ -862,7 +862,7 @@ def watch(self, pipeline=None, full_document=None, resume_after=None,
 
         .. versionadded:: 3.7
 
-        .. mongodoc:: changeStreams
+        .. seealso:: The MongoDB documentation on `changeStreams <https://dochub.mongodb.org/core/changeStreams>`_.
 
         .. _change streams specification:
             https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.rst