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

ShaneHarvey · ShaneHarvey · commit c9ace20af659 · 2021-08-18T14:25:20.000-07:00
diff --git a/bson/dbref.py b/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")
diff --git a/bson/objectid.py b/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
diff --git a/doc/conf.py b/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']
diff --git a/doc/examples/encryption.rst b/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
 ------------
diff --git a/doc/examples/geo.rst b/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
 ---------------------------
diff --git a/doc/examples/high_availability.rst b/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
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/mongo_extensions.py b/doc/mongo_extensions.py
diff --git a/gridfs/__init__.py b/gridfs/__init__.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")
diff --git a/gridfs/grid_file.py b/gridfs/grid_file.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)
diff --git a/pymongo/change_stream.py b/pymongo/change_stream.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,
diff --git a/pymongo/client_session.py b/pymongo/client_session.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:
 
diff --git a/pymongo/collection.py b/pymongo/collection.py
@@ -144,7 +144,7 @@ def __init__(self, database, name, create=False, codec_options=None,
         .. versionadded:: 2.1
            uuid_subtype attribute
 
-        .. mongodoc:: collections
+        .. seealso:: The MongoDB documentation on `collections <https://dochub.mongodb.org/core/collections>`_.
         """
         super(Collection, self).__init__(
             codec_options or database.codec_options,
@@ -1395,7 +1395,7 @@ def find(self, *args, **kwargs):
 
         .. _PYTHON-500: https://jira.mongodb.org/browse/PYTHON-500
 
-        .. mongodoc:: find
+        .. seealso:: The MongoDB documentation on `find <https://dochub.mongodb.org/core/find>`_.
 
         """
         return Cursor(self, *args, **kwargs)
@@ -1776,7 +1776,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
         """
@@ -2224,7 +2224,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
diff --git a/pymongo/command_cursor.py b/pymongo/command_cursor.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__(
diff --git a/pymongo/cursor.py b/pymongo/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
@@ -1236,7 +1236,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)
 
@@ -1253,7 +1253,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()
diff --git a/pymongo/database.py b/pymongo/database.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.
@@ -471,7 +471,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
@@ -603,7 +603,7 @@ def command(self, command, value=1, check=True,
 
         .. _PYTHON-500: https://jira.mongodb.org/browse/PYTHON-500
 
-        .. 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())
diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.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
