From c146017de1012499283539aebb864b44d82d4eed Mon Sep 17 00:00:00 2001
From: Steven Silvester <steven.silvester@ieee.org>
Date: Tue, 31 Oct 2023 07:55:24 -0500
Subject: [PATCH] PYTHON-4012 Adopt more RST static checks (#1412)

---
 .pre-commit-config.yaml             |  14 ++
 CONTRIBUTING.rst                    |   2 +-
 doc/changelog.rst                   | 194 ++++++++++++++--------------
 doc/developer/periodic_executor.rst |   8 +-
 doc/examples/authentication.rst     |   2 +-
 doc/examples/datetimes.rst          |  14 +-
 doc/examples/server_selection.rst   |   2 +-
 doc/examples/timeouts.rst           |   2 +-
 doc/examples/type_hints.rst         |  12 +-
 doc/faq.rst                         |   8 +-
 doc/migrate-to-pymongo4.rst         |   2 +-
 tox.ini                             |   2 +-
 12 files changed, 138 insertions(+), 124 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 3a90118fc1..00a03defcd 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -38,6 +38,20 @@ repos:
     additional_dependencies:
     - black==22.3.0
 
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: "v1.10.0"
+  hooks:
+    - id: rst-backticks
+    - id: rst-directive-colons
+    - id: rst-inline-touching-normal
+
+- repo: https://github.com/rstcheck/rstcheck
+  rev: v6.2.0
+  hooks:
+  - id: rstcheck
+    additional_dependencies: [sphinx]
+    args: ["--ignore-directives=doctest,testsetup,todo,automodule","--ignore-substitutions=release", "--report-level=error"]
+
 # We use the Python version instead of the original version which seems to require Docker
 # https://github.com/koalaman/shellcheck-precommit
 - repo: https://github.com/shellcheck-py/shellcheck-py
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 0d0e47c619..07d6f1d77c 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -115,7 +115,7 @@ To run ``pre-commit`` manually, run::
 
     pre-commit run --all-files
 
-To run a manual hook like `flake8` manually, run::
+To run a manual hook like ``flake8`` manually, run::
 
     pre-commit run --all-files --hook-stage manual flake8
 
diff --git a/doc/changelog.rst b/doc/changelog.rst
index 9f790a0961..b12382e3a8 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -572,7 +572,7 @@ Breaking Changes in 4.0
 - Comparing two :class:`~pymongo.mongo_client.MongoClient` instances now
   uses a set of immutable properties rather than
   :attr:`~pymongo.mongo_client.MongoClient.address` which can change.
-- Removed the `disable_md5` parameter for :class:`~gridfs.GridFSBucket` and
+- Removed the ``disable_md5`` parameter for :class:`~gridfs.GridFSBucket` and
   :class:`~gridfs.GridFS`. See :ref:`removed-gridfs-checksum` for details.
 - pymongocrypt 1.2.0 or later is now required for client side field level
   encryption support.
@@ -585,10 +585,10 @@ Notable improvements
 - Added the ``maxConnecting`` URI and
   :class:`~pymongo.mongo_client.MongoClient` keyword argument.
 - :class:`~pymongo.mongo_client.MongoClient` now accepts a URI and keyword
-  argument `srvMaxHosts` that limits the number of mongos-like hosts a client
+  argument ``srvMaxHosts`` that limits the number of mongos-like hosts a client
   will connect to. More specifically, when a mongodb+srv:// connection string
-  resolves to more than `srvMaxHosts` number of hosts, the client will randomly
-  choose a `srvMaxHosts` sized subset of hosts.
+  resolves to more than ``srvMaxHosts`` number of hosts, the client will randomly
+  choose a ``srvMaxHosts`` sized subset of hosts.
 - Added :attr:`pymongo.mongo_client.MongoClient.options` for read-only access
   to a client's configuration options.
 - Support for the "kmip" KMS provider for client side field level encryption.
@@ -747,7 +747,7 @@ Changes in Version 3.12.0
 - Iterating over :class:`gridfs.grid_file.GridOut` now moves through
   the file line by line instead of chunk by chunk, and does not
   restart at the top for subsequent iterations on the same object.
-  Call `seek(0)` to reset the iterator.
+  Call ``seek(0)`` to reset the iterator.
 
 Notable improvements
 ....................
@@ -1200,9 +1200,9 @@ Changes in Version 3.8.0
   is expected to require a :meth:`~pymongo.cursor.Cursor.hint` when using
   min/max starting in MongoDB 4.2.
 - Documented support for the uuidRepresentation URI option, which has been
-  supported since PyMongo 2.7. Valid values are `pythonLegacy` (the default),
-  `javaLegacy`, `csharpLegacy` and `standard`. New applications should consider
-  setting this to `standard` for cross language compatibility.
+  supported since PyMongo 2.7. Valid values are ``pythonLegacy`` (the default),
+  ``javaLegacy``, ``csharpLegacy`` and ``standard``. New applications should consider
+  setting this to ``standard`` for cross language compatibility.
 - :class:`~bson.raw_bson.RawBSONDocument` now validates that the ``bson_bytes``
   passed in represent a single bson document. Earlier versions would mistakenly
   accept multiple bson documents.
@@ -1305,7 +1305,7 @@ Version 3.7 adds support for MongoDB 4.0. Highlights include:
     :ref:`PLAIN <sasl_plain>`, and :ref:`MONGODB-X509 <mongodb_x509>`
     mechanisms can also be used to avoid issues with OpenSSL in FIPS
     environments.
-  - MD5 checksums are now optional in GridFS. See the `disable_md5` option
+  - MD5 checksums are now optional in GridFS. See the ``disable_md5`` option
     of :class:`~gridfs.GridFS` and :class:`~gridfs.GridFSBucket`.
   - :class:`~bson.objectid.ObjectId` machine bytes are now hashed using
     `FNV-1a
@@ -1324,7 +1324,7 @@ Version 3.7 adds support for MongoDB 4.0. Highlights include:
   authentication mechanism defaults to $external.
 - wtimeoutMS is once again supported as a URI option.
 - When using unacknowledged write concern and connected to MongoDB server
-  version 3.6 or greater, the `bypass_document_validation` option is now
+  version 3.6 or greater, the ``bypass_document_validation`` option is now
   supported in the following write helpers:
   :meth:`~pymongo.collection.Collection.insert_one`,
   :meth:`~pymongo.collection.Collection.replace_one`,
@@ -1334,7 +1334,7 @@ Version 3.7 adds support for MongoDB 4.0. Highlights include:
 Deprecations:
 
 - Deprecated :meth:`pymongo.collection.Collection.count` and
-  :meth:`pymongo.cursor.Cursor.count`. These two methods use the `count`
+  :meth:`pymongo.cursor.Cursor.count`. These two methods use the ``count``
   command and `may or may not be accurate
   <https://mongodb.com/docs/manual/reference/command/count/#behavior>`_,
   depending on the options used and connected MongoDB topology. Use
@@ -1344,7 +1344,7 @@ Deprecations:
   deprecated in MongoDB 3.6 and removed in MongoDB 4.0.
 - Deprecated the max_scan option of :meth:`~pymongo.collection.Collection.find`
   and :meth:`~pymongo.collection.Collection.find_one`. The option was
-  deprecated in MongoDB 4.0. Use `maxTimeMS` instead.
+  deprecated in MongoDB 4.0. Use ``maxTimeMS`` instead.
 - Deprecated :meth:`~pymongo.mongo_client.MongoClient.close_cursor`. Use
   :meth:`~pymongo.cursor.Cursor.close` instead.
 - Deprecated :meth:`~pymongo.mongo_client.MongoClient.database_names`. Use
@@ -1446,7 +1446,7 @@ Highlights include:
 
 Deprecations:
 
-- The `useCursor` option for :meth:`~pymongo.collection.Collection.aggregate`
+- The ``useCursor`` option for :meth:`~pymongo.collection.Collection.aggregate`
   is deprecated. The option was only necessary when upgrading from MongoDB
   2.4 to MongoDB 2.6. MongoDB 2.4 is no longer supported.
 - The :meth:`~pymongo.database.Database.add_user` and
@@ -1511,13 +1511,13 @@ Highlights include:
 - Increased the performance of using :class:`~bson.raw_bson.RawBSONDocument`.
 - Increased the performance of
   :meth:`~pymongo.mongo_client.MongoClient.database_names` by using the
-  `nameOnly` option for listDatabases when available.
+  ``nameOnly`` option for listDatabases when available.
 - Increased the performance of
   :meth:`~pymongo.collection.Collection.bulk_write` by reducing the memory
   overhead of :class:`~pymongo.operations.InsertOne`,
   :class:`~pymongo.operations.DeleteOne`, and
   :class:`~pymongo.operations.DeleteMany`.
-- Added the `collation` option to :class:`~pymongo.operations.DeleteOne`,
+- Added the ``collation`` option to :class:`~pymongo.operations.DeleteOne`,
   :class:`~pymongo.operations.DeleteMany`,
   :class:`~pymongo.operations.ReplaceOne`,
   :class:`~pymongo.operations.UpdateOne`, and
@@ -1531,13 +1531,13 @@ Highlights include:
 
 Changes and Deprecations:
 
-- :meth:`~pymongo.collection.Collection.find` has new options `return_key`,
-  `show_record_id`, `snapshot`, `hint`, `max_time_ms`, `max_scan`, `min`, `max`,
-  and `comment`. Deprecated the option `modifiers`.
+- :meth:`~pymongo.collection.Collection.find` has new options ``return_key``,
+  ``show_record_id``, ``snapshot``, ``hint``, ``max_time_ms``, ``max_scan``, ``min``, ``max``,
+  and ``comment``. Deprecated the option ``modifiers``.
 - Deprecated :meth:`~pymongo.collection.Collection.group`. The group command
   was deprecated in MongoDB 3.4 and is expected to be removed in MongoDB 3.6.
   Applications should use :meth:`~pymongo.collection.Collection.aggregate`
-  with the `$group` pipeline stage instead.
+  with the ``$group`` pipeline stage instead.
 - Deprecated :meth:`~pymongo.database.Database.authenticate`. Authenticating
   multiple users conflicts with support for logical sessions in MongoDB 3.6.
   To authenticate as multiple users, create multiple instances of
@@ -1547,9 +1547,9 @@ Changes and Deprecations:
 - Deprecated :class:`~pymongo.database.SystemJS`.
 - Deprecated :meth:`~pymongo.mongo_client.MongoClient.get_default_database`.
   Applications should use
-  :meth:`~pymongo.mongo_client.MongoClient.get_database` without the `name`
+  :meth:`~pymongo.mongo_client.MongoClient.get_database` without the ```name```
   parameter instead.
-- Deprecated the MongoClient option `socketKeepAlive`. It now defaults to true
+- Deprecated the MongoClient option ``socketKeepAlive```. It now defaults to true
   and disabling it is not recommended, see `does TCP keepalive time affect
   MongoDB Deployments?
   <https://mongodb.com/docs/manual/faq/diagnostics/#does-tcp-keepalive-time-affect-mongodb-deployments->`_
@@ -1561,7 +1561,7 @@ Changes and Deprecations:
   :const:`~bson.json_util.RELAXED_JSON_OPTIONS` or
   :const:`~bson.json_util.CANONICAL_JSON_OPTIONS` instead.
 - If a custom :class:`~bson.codec_options.CodecOptions` is passed to
-  :class:`RawBSONDocument`, its `document_class` must be
+  :class:`RawBSONDocument`, its ``document_class``` must be
   :class:`RawBSONDocument`.
 - :meth:`~pymongo.collection.Collection.list_indexes` no longer raises
   OperationFailure when the collection (or database) does not exist on
@@ -1706,7 +1706,7 @@ Changes in Version 3.2.2
 ------------------------
 
 Version 3.2.2 fixes a few issues reported since the release of 3.2.1, including
-a fix for using the `connect` option in the MongoDB URI and support for setting
+a fix for using the ``connect`` option in the MongoDB URI and support for setting
 the batch size for a query to 1 when using MongoDB 3.2+.
 
 Issues Resolved
@@ -1750,7 +1750,7 @@ Highlights include:
     :meth:`~pymongo.collection.Collection.find_one_and_replace`,
     :meth:`~pymongo.collection.Collection.find_one_and_update`, and
     :meth:`~pymongo.collection.Collection.find_one_and_delete`.
-  - Support for the new `bypassDocumentValidation` option in write
+  - Support for the new ``bypassDocumentValidation`` option in write
     helpers.
 
 - Support for reading and writing raw BSON with
@@ -1794,10 +1794,10 @@ Highlights include:
 
 - Command monitoring support. See :mod:`~pymongo.monitoring` for details.
 - Configurable error handling for :exc:`UnicodeDecodeError`. See the
-  `unicode_decode_error_handler` option of
+  ``unicode_decode_error_handler`` option of
   :class:`~bson.codec_options.CodecOptions`.
 - Optional automatic timezone conversion when decoding BSON datetime. See the
-  `tzinfo` option of :class:`~bson.codec_options.CodecOptions`.
+  ``tzinfo`` option of :class:`~bson.codec_options.CodecOptions`.
 - An implementation of :class:`~gridfs.GridFSBucket` from the new GridFS spec.
 - Compliance with the new Connection String spec.
 - Reduced idle CPU usage in Python 2.
@@ -1920,7 +1920,7 @@ applied to documents returned by the new methods
 SSL/TLS changes
 ...............
 
-When `ssl` is ``True`` the `ssl_cert_reqs` option now defaults to
+When ``ssl`` is ``True`` the ``ssl_cert_reqs`` option now defaults to
 :attr:`ssl.CERT_REQUIRED` if not provided. PyMongo will attempt to load OS
 provided CA certificates to verify the server, raising
 :exc:`~pymongo.errors.ConfigurationError` if it cannot.
@@ -2067,12 +2067,12 @@ Cursor management changes
 :meth:`~pymongo.mongo_client.MongoClient.set_cursor_manager` are no longer
 deprecated. If you subclass :class:`~pymongo.cursor_manager.CursorManager`
 your implementation of :meth:`~pymongo.cursor_manager.CursorManager.close`
-must now take a second parameter, `address`. The ``BatchCursorManager`` class
+must now take a second parameter, ``address``. The ``BatchCursorManager`` class
 is removed.
 
 The second parameter to :meth:`~pymongo.mongo_client.MongoClient.close_cursor`
 is renamed from ``_conn_id`` to ``address``.
-:meth:`~pymongo.mongo_client.MongoClient.kill_cursors` now accepts an `address`
+:meth:`~pymongo.mongo_client.MongoClient.kill_cursors` now accepts an ``address``
 parameter.
 
 :class:`~pymongo.database.Database` changes
@@ -2107,13 +2107,13 @@ The following methods have been added:
 
 The following methods have been changed:
 
-- :meth:`~pymongo.database.Database.command`. Support for `as_class`,
-  `uuid_subtype`, `tag_sets`, and `secondary_acceptable_latency_ms` have been
+- :meth:`~pymongo.database.Database.command`. Support for ``as_class``,
+  ``uuid_subtype``, ``tag_sets``, and ``secondary_acceptable_latency_ms`` have been
   removed. You can instead pass an instance of
-  :class:`~bson.codec_options.CodecOptions` as `codec_options` and an instance
+  :class:`~bson.codec_options.CodecOptions` as ``codec_options`` and an instance
   of a read preference class from :mod:`~pymongo.read_preferences` as
-  `read_preference`. The `fields` and `compile_re` options are also removed.
-  The `fields` options was undocumented and never really worked. Regular
+  ``read_preference``. The ``fields`` and ``compile_re`` options are also removed.
+  The ``fields`` options was undocumented and never really worked. Regular
   expressions are always decoded to :class:`~bson.regex.Regex`.
 
 The following methods have been deprecated:
@@ -2177,9 +2177,9 @@ The following methods have changed:
 - :meth:`~pymongo.collection.Collection.distinct` now optionally takes a filter
   argument.
 - :meth:`~pymongo.collection.Collection.create_index` no longer caches
-  indexes, therefore the `cache_for` parameter has been removed. It also
-  no longer supports the `bucket_size` and `drop_dups` aliases for `bucketSize`
-  and `dropDups`.
+  indexes, therefore the ``cache_for`` parameter has been removed. It also
+  no longer supports the ``bucket_size`` and ``drop_dups`` aliases for ``bucketSize``
+  and ``dropDups``.
 
 The following methods are deprecated:
 
@@ -2227,13 +2227,13 @@ The following find/find_one options have been removed:
 - tag_sets (use one of the read preference classes from
   :mod:`~pymongo.read_preferences` and
   :meth:`~pymongo.collection.Collection.with_options` instead)
-- secondary_acceptable_latency_ms (use the `localThresholdMS` URI option
+- secondary_acceptable_latency_ms (use the ``localThresholdMS`` URI option
   instead)
-- max_scan (use the new `modifiers` option instead)
-- snapshot (use the new `modifiers` option instead)
-- tailable (use the new `cursor_type` option instead)
-- await_data (use the new `cursor_type` option instead)
-- exhaust (use the new `cursor_type` option instead)
+- max_scan (use the new ``modifiers`` option instead)
+- snapshot (use the new ``modifiers`` option instead)
+- tailable (use the new ``cursor_type`` option instead)
+- await_data (use the new ``cursor_type`` option instead)
+- exhaust (use the new ``cursor_type`` option instead)
 - as_class (use :meth:`~pymongo.collection.Collection.with_options` with
   :class:`~bson.codec_options.CodecOptions` instead)
 - compile_re (BSON regular expressions are always decoded to
@@ -2246,9 +2246,9 @@ The following find/find_one options are deprecated:
 The following renames need special handling.
 
 - timeout -> no_cursor_timeout -
-  The default for `timeout` was True. The default for `no_cursor_timeout` is
-  False. If you were previously passing False for `timeout` you must pass
-  **True** for `no_cursor_timeout` to keep the previous behavior.
+  The default for ``timeout`` was True. The default for ``no_cursor_timeout`` is
+  False. If you were previously passing False for ``t`imeout`` you must pass
+  **True** for ``no_cursor_timeout`` to keep the previous behavior.
 
 :mod:`~pymongo.errors` changes
 ..............................
@@ -2265,7 +2265,7 @@ The unsupported methods, the class, and the exception are all deleted.
 :mod:`~bson` changes
 ....................
 
-The `compile_re` option is removed from all methods
+The ``compile_re`` option is removed from all methods
 that accepted it in :mod:`~bson` and :mod:`~bson.json_util`. Additionally, it
 is removed from :meth:`~pymongo.collection.Collection.find`,
 :meth:`~pymongo.collection.Collection.find_one`,
@@ -2283,7 +2283,7 @@ allows BSON int64 to be round tripped without losing type information in
 python 3. Note that if you store a python long (or a python int larger than
 4 bytes) it will be returned from PyMongo as :class:`~bson.int64.Int64`.
 
-The `as_class`, `tz_aware`, and `uuid_subtype` options are removed from all
+The ``as_class``, ``tz_aware``, and ``uuid_subtype`` options are removed from all
 BSON encoding and decoding methods. Use
 :class:`~bson.codec_options.CodecOptions` to configure these options. The
 APIs affected are:
@@ -2375,7 +2375,7 @@ improves an error message when decoding BSON as well as fixes a couple other
 issues including :meth:`~pymongo.collection.Collection.aggregate` ignoring
 :attr:`~pymongo.collection.Collection.codec_options` and
 :meth:`~pymongo.database.Database.command` raising a superfluous
-`DeprecationWarning`.
+``DeprecationWarning``.
 
 Issues Resolved
 ...............
@@ -2683,7 +2683,7 @@ Important new features:
 - Support aggregation output as a :class:`~pymongo.cursor.Cursor`. See
   :meth:`~pymongo.collection.Collection.aggregate` for details.
 
-.. warning:: SIGNIFICANT BEHAVIOR CHANGE in 2.6. Previously, `max_pool_size`
+.. warning:: SIGNIFICANT BEHAVIOR CHANGE in 2.6. Previously, ``max_pool_size``
   would limit only the idle sockets the pool would hold onto, not the
   number of open sockets. The default has also changed, from 10 to 100.
   If you pass a value for ``max_pool_size`` make sure it is large enough for
@@ -2808,7 +2808,7 @@ Important new features:
 - :class:`~pymongo.cursor.Cursor` can be copied with functions from the :mod:`copy`
   module.
 - The :meth:`~pymongo.database.Database.set_profiling_level` method now supports
-  a `slow_ms` option.
+  a ``slow_ms`` option.
 - The replica set monitor task (used by
   :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` and
   :class:`~pymongo.replica_set_connection.ReplicaSetConnection`) is a daemon thread
@@ -3028,12 +3028,12 @@ Important New Features:
   independently at the connection, database, collection or query level. Each
   level will inherit settings from the previous level and each level can
   override the previous level's setting.
-- PyMongo now supports the `await_data` and `partial` cursor flags. If the
-  `await_data` flag is set on a `tailable` cursor the server will block for
-  some extra time waiting for more data to return. The `partial` flag tells
+- PyMongo now supports the ``await_data`` and ``partial`` cursor flags. If the
+  ``await_data`` flag is set on a ``tailable`` cursor the server will block for
+  some extra time waiting for more data to return. The ``partial`` flag tells
   a mongos to return partial data for a query if not all shards are available.
-- :meth:`~pymongo.collection.Collection.map_reduce` will accept a `dict` or
-  instance of :class:`~bson.son.SON` as the `out` parameter.
+- :meth:`~pymongo.collection.Collection.map_reduce` will accept a ``dict`` or
+  instance of :class:`~bson.son.SON` as the ``out`` parameter.
 - The URI parser has been moved into its own module and can be used directly
   by application code.
 - AutoReconnect exception now provides information about the error that
@@ -3045,9 +3045,9 @@ Important New Features:
 API changes:
 
 - If only one host:port pair is specified :class:`~pymongo.connection.Connection`
-  will make a direct connection to only that host. Please note that `slave_okay`
-  must be `True` in order to query from a secondary.
-- If more than one host:port pair is specified or the `replicaset` option is
+  will make a direct connection to only that host. Please note that ``slave_okay``
+  must be ``True`` in order to query from a secondary.
+- If more than one host:port pair is specified or the ``replicaset`` option is
   used PyMongo will treat the specified host:port pair(s) as a seed list and
   connect using replica set behavior.
 
@@ -3072,7 +3072,7 @@ Version 1.11 adds a few new features and fixes a few more bugs.
 New Features:
 
 - Basic IPv6 support: pymongo prefers IPv4 but will try IPv6. You can
-  also specify an IPv6 address literal in the `host` parameter or a
+  also specify an IPv6 address literal in the ``host`` parameter or a
   MongoDB URI provided it is enclosed in '[' and ']'.
 - max_pool_size option: previously pymongo had a hard coded pool size
   of 10 connections. With this change you can specify a different pool
@@ -3090,10 +3090,10 @@ API changes:
 - :meth:`~pymongo.database.Database.validate_collection` now returns a
   dict instead of a string. This change was required to deal with an
   API change on the server. This method also now takes the optional
-  `scandata` and `full` parameters. See the documentation for more
+  ``scandata`` and ``full`` parameters. See the documentation for more
   details.
 
-.. warning::  The `pool_size`, `auto_start_request`, and `timeout` parameters
+.. warning::  The ``pool_size``, ``auto_start_request```, and ``timeout`` parameters
               for :class:`~pymongo.connection.Connection` have been completely
               removed in this release. They were deprecated in pymongo-1.4 and
               have had no effect since then. Please make sure that your code
@@ -3135,9 +3135,9 @@ There are two behavior changes to be aware of:
   Previously the read would be sent to one randomly chosen slave and
   :class:`~pymongo.errors.AutoReconnect` was immediately raised in case
   of a connection failure.
-- A Python `long` is now always BSON encoded as an int64. Previously the
-  encoding was based only on the value of the field and a `long` with a
-  value less than `2147483648` or greater than `-2147483649` would always
+- A Python ``long`` is now always BSON encoded as an int64. Previously the
+  encoding was based only on the value of the field and a ``long`` with a
+  value less than ``2147483648`` or greater than ``-2147483649`` would always
   be BSON encoded as an int32.
 
 Issues resolved
@@ -3182,7 +3182,7 @@ server for the maximum BSON document size it supports.
    collections for map/reduce results. An output collection name must be
    provided and the output will replace any existing output collection with
    the same name. :meth:`~pymongo.collection.Collection.map_reduce` now
-   requires the `out` parameter.
+   requires the ``out`` parameter.
 
 Issues resolved
 ...............
@@ -3205,7 +3205,7 @@ Issues resolved
 - PYTHON-169: Support deepcopy of DBRef.
 - PYTHON-167: Duplicate of PYTHON-166.
 - PYTHON-166: Fixes a concurrency issue.
-- PYTHON-158: Add code and err string to `db assertion` messages.
+- PYTHON-158: Add code and err string to ``db assertion`` messages.
 
 Changes in Version 1.9
 ----------------------
@@ -3282,7 +3282,7 @@ rather than :class:`pymongo.errors.PyMongoError`.
   :class:`~pymongo.connection.Connection` has been idle for a while.
 - added :meth:`~pymongo.database.SystemJS.list` to
   :class:`~pymongo.database.SystemJS`.
-- added `file_document` argument to :meth:`~gridfs.grid_file.GridOut`
+- added ``file_document`` argument to :meth:`~gridfs.grid_file.GridOut`
   to allow initializing from an existing file document.
 - raise :class:`~pymongo.errors.TimeoutError` even if the
   ``getLastError`` command was run manually and not through "safe"
@@ -3302,13 +3302,13 @@ Changes in Version 1.8
 ----------------------
 
 Version 1.8 adds support for connecting to replica sets, specifying
-per-operation values for `w` and `wtimeout`, and decoding to
+per-operation values for ``w`` and ``wtimeout``, and decoding to
 timezone-aware datetimes.
 
 - fixed a reference leak in the C extension when decoding a
   :class:`~bson.dbref.DBRef`.
-- added support for `w`, `wtimeout`, and `fsync` (and any other
-  options for `getLastError`) to "safe mode" operations.
+- added support for ``w``, ``wtimeout``, and ``fsync`` (and any other
+  options for ``getLastError``) to "safe mode" operations.
 - added :attr:`~pymongo.connection.Connection.nodes` property.
 - added a maximum pool size of 10 sockets.
 - added support for replica sets.
@@ -3326,9 +3326,9 @@ timezone-aware datetimes.
   :class:`~bson.max_key.MaxKey` and
   :class:`~bson.timestamp.Timestamp` to :mod:`~bson.json_util`.
 - added support for decoding datetimes as aware (UTC) - it is highly
-  recommended to enable this by setting the `tz_aware` parameter to
+  recommended to enable this by setting the ``tz_aware`` parameter to
   :meth:`~pymongo.connection.Connection` to ``True``.
-- added `network_timeout` option for individual calls to
+- added ``network_timeout`` option for individual calls to
   :meth:`~pymongo.collection.Collection.find` and
   :meth:`~pymongo.collection.Collection.find_one`.
 - added :meth:`~gridfs.GridFS.exists` to check if a file exists in
@@ -3359,11 +3359,11 @@ highlights is `here
   support for querying unique status and other index information.
 - added :attr:`~pymongo.connection.Connection.document_class`, to
   specify class for returned documents.
-- added `as_class` argument for
+- added ``as_class`` argument for
   :meth:`~pymongo.collection.Collection.find`, and in the BSON decoder.
 - added support for creating :class:`~bson.timestamp.Timestamp`
   instances using a :class:`~datetime.datetime`.
-- allow `dropTarget` argument for
+- allow ``dropTarget`` argument for
   :class:`~pymongo.collection.Collection.rename`.
 - handle aware :class:`~datetime.datetime` instances, by converting to
   UTC.
@@ -3373,13 +3373,13 @@ highlights is `here
 - use `y2038 <https://github.com/evalEmpire/y2038/>`_ for time handling in
   the C extension - eliminates 2038 problems when extension is
   installed.
-- added `sort` parameter to
+- added ``sort`` parameter to
   :meth:`~pymongo.collection.Collection.find`
 - finalized deprecation of changes from versions **<= 1.4**
 - take any non-:class:`dict` as an ``"_id"`` query for
   :meth:`~pymongo.collection.Collection.find_one` or
   :meth:`~pymongo.collection.Collection.remove`
-- added ability to pass a :class:`dict` for `fields` argument to
+- added ability to pass a :class:`dict` for ``fields`` argument to
   :meth:`~pymongo.collection.Collection.find` (supports ``"$slice"``
   and field negation)
 - simplified code to find master, since paired setups don't always have
@@ -3421,7 +3421,7 @@ Changes in Version 1.5.1
 - added :data:`~gridfs.grid_file.GridFile._id` property for
   :class:`~gridfs.grid_file.GridFile` instances.
 - fix for making a :class:`~pymongo.connection.Connection` (with
-  `slave_okay` set) directly to a slave in a replica pair.
+  ``slave_okay`` set) directly to a slave in a replica pair.
 - accept kwargs for
   :meth:`~pymongo.collection.Collection.create_index` and
   :meth:`~pymongo.collection.Collection.ensure_index` to support all
@@ -3433,7 +3433,7 @@ Changes in Version 1.5.1
 Changes in Version 1.5
 ----------------------
 - added subtype constants to :mod:`~bson.binary` module.
-- DEPRECATED `options` argument to
+- DEPRECATED ``options`` argument to
   :meth:`~pymongo.collection.Collection` and
   :meth:`~pymongo.database.Database.create_collection` in favor of
   kwargs.
@@ -3443,7 +3443,7 @@ Changes in Version 1.5
   might have more data to return (useful for tailable cursors).
 - added :class:`~bson.timestamp.Timestamp` to better support
   dealing with internal MongoDB timestamps.
-- added `name` argument for
+- added ``name`` argument for
   :meth:`~pymongo.collection.Collection.create_index` and
   :meth:`~pymongo.collection.Collection.ensure_index`.
 - fixed connection pooling w/ fork
@@ -3495,7 +3495,7 @@ Other changes:
   for example.
 - added :class:`~pymongo.errors.DuplicateKeyError` for calls to
   :meth:`~pymongo.collection.Collection.insert` or
-  :meth:`~pymongo.collection.Collection.update` with `safe` set to
+  :meth:`~pymongo.collection.Collection.update` with ``safe`` set to
   ``True``.
 - removed :mod:`~pymongo.thread_util`.
 - added :meth:`~pymongo.database.Database.add_user` and
@@ -3508,7 +3508,7 @@ Other changes:
   is raised.
 - simplification of connection pooling - makes driver ~2x faster for
   simple benchmarks. see :ref:`connection-pooling` for more information.
-- DEPRECATED `pool_size`, `auto_start_request` and `timeout`
+- DEPRECATED ``pool_size``, ``auto_start_request`` and ``timeout``
   parameters to :class:`~pymongo.connection.Connection`. DEPRECATED
   :meth:`~pymongo.connection.Connection.start_request`.
 - use :meth:`socket.sendall`.
@@ -3519,7 +3519,7 @@ Other changes:
 - deprecate :meth:`~pymongo.database.Database._command` in favor of
   :meth:`~pymongo.database.Database.command`.
 - send all commands without wrapping as ``{"query": ...}``.
-- support string as `key` argument to
+- support string as ``key`` argument to
   :meth:`~pymongo.collection.Collection.group` (keyf) and run all
   groups as commands.
 - support for equality testing for :class:`~bson.code.Code`
@@ -3567,7 +3567,7 @@ Changes in Version 1.2.1
 
 Changes in Version 1.2
 ----------------------
-- `spec` parameter for :meth:`~pymongo.collection.Collection.remove` is
+- ``spec`` parameter for :meth:`~pymongo.collection.Collection.remove` is
   now optional to allow for deleting all documents in a
   :class:`~pymongo.collection.Collection`
 - always wrap queries with ``{query: ...}`` even when no special options -
@@ -3601,15 +3601,15 @@ Changes in Version 1.1.2
 
 Changes in Version 1.1.1
 ------------------------
-- added `multi` parameter for
+- added ``multi`` parameter for
   :meth:`~pymongo.collection.Collection.update`
 - fix unicode regex patterns with C extension
 - added :meth:`~pymongo.collection.Collection.distinct`
-- added `database` support for :class:`~bson.dbref.DBRef`
+- added ``database`` support for :class:`~bson.dbref.DBRef`
 - added :mod:`~bson.json_util` with helpers for encoding / decoding
   special types to JSON
 - DEPRECATED :meth:`pymongo.cursor.Cursor.__len__` in favor of
-  :meth:`~pymongo.cursor.Cursor.count` with `with_limit_and_skip` set
+  :meth:`~pymongo.cursor.Cursor.count` with ``with_limit_and_skip`` set
   to ``True`` due to performance regression
 - switch documentation to Sphinx
 
@@ -3622,18 +3622,18 @@ Changes in Version 1.1
 - fix :class:`~bson.objectid.ObjectId` generation when using
   :mod:`multiprocessing`
 - added :attr:`~pymongo.cursor.Cursor.collection`
-- added `network_timeout` parameter for
+- added ``network_timeout`` parameter for
   :meth:`~pymongo.connection.Connection`
-- DEPRECATED `slave_okay` parameter for individual queries
-- fix for `safe` mode when multi-threaded
-- added `safe` parameter for :meth:`~pymongo.collection.Collection.remove`
-- added `tailable` parameter for :meth:`~pymongo.collection.Collection.find`
+- DEPRECATED ``slave_okay`` parameter for individual queries
+- fix for ``safe`` mode when multi-threaded
+- added ``safe`` parameter for :meth:`~pymongo.collection.Collection.remove`
+- added ``tailable`` parameter for :meth:`~pymongo.collection.Collection.find`
 
 Changes in Version 1.0
 ----------------------
 - fixes for
   :class:`~pymongo.master_slave_connection.MasterSlaveConnection`
-- added `finalize` parameter for :meth:`~pymongo.collection.Collection.group`
+- added ``finalize`` parameter for :meth:`~pymongo.collection.Collection.group`
 - improvements to :meth:`~pymongo.collection.Collection.insert` speed
 - improvements to :mod:`gridfs` speed
 - added :meth:`~pymongo.cursor.Cursor.__getitem__` and
@@ -3663,9 +3663,9 @@ Changes in Version 0.15
 -----------------------
 - fix string representation of :class:`~bson.objectid.ObjectId`
   instances
-- added `timeout` parameter for
+- added ``timeout`` parameter for
   :meth:`~pymongo.collection.Collection.find`
-- allow scope for `reduce` function in
+- allow scope for ``reduce`` function in
   :meth:`~pymongo.collection.Collection.group`
 
 Changes in Version 0.14.2
@@ -3682,7 +3682,7 @@ Changes in Version 0.14
 -----------------------
 - support for long in :class:`~bson.BSON`
 - added :meth:`~pymongo.collection.Collection.rename`
-- added `snapshot` parameter for
+- added ``snapshot`` parameter for
   :meth:`~pymongo.collection.Collection.find`
 
 Changes in Version 0.13
@@ -3724,7 +3724,7 @@ Changes in Version 0.11
 - better build failure detection
 - driver support for selecting fields in sub-documents
 - disallow insertion of invalid key names
-- added `timeout` parameter for :meth:`~pymongo.connection.Connection`
+- added ``timeout`` parameter for :meth:`~pymongo.connection.Connection`
 
 Changes in Version 0.10.3
 -------------------------
diff --git a/doc/developer/periodic_executor.rst b/doc/developer/periodic_executor.rst
index 9cb0ce0eb9..effe18efca 100644
--- a/doc/developer/periodic_executor.rst
+++ b/doc/developer/periodic_executor.rst
@@ -5,7 +5,7 @@ Periodic Executors
 
 PyMongo implements a :class:`~periodic_executor.PeriodicExecutor` for two
 purposes: as the background thread for :class:`~monitor.Monitor`, and to
-regularly check if there are `OP_KILL_CURSORS` messages that must be sent to the server.
+regularly check if there are ``OP_KILL_CURSORS`` messages that must be sent to the server.
 
 Killing Cursors
 ---------------
@@ -17,7 +17,7 @@ the cursor before finishing iteration::
     for doc in collection.find():
         raise Exception()
 
-We try to send an `OP_KILL_CURSORS` to the server to tell it to clean up the
+We try to send an ``OP_KILL_CURSORS`` to the server to tell it to clean up the
 server-side cursor. But we must not take any locks directly from the cursor's
 destructor (see `PYTHON-799`_), so we cannot safely use the PyMongo data
 structures required to send a message. The solution is to add the cursor's id
@@ -26,7 +26,7 @@ to an array on the :class:`~mongo_client.MongoClient` without taking any locks.
 Each client has a :class:`~periodic_executor.PeriodicExecutor` devoted to
 checking the array for cursor ids. Any it sees are the result of cursors that
 were freed while the server-side cursor was still open. The executor can safely
-take the locks it needs in order to send the `OP_KILL_CURSORS` message.
+take the locks it needs in order to send the ``OP_KILL_CURSORS`` message.
 
 .. _PYTHON-799: https://jira.mongodb.org/browse/PYTHON-799
 
@@ -103,7 +103,7 @@ the exponential backoff is restarted frequently. Overall, the condition variable
 is not waking a few times a second, but hundreds of times. (See `PYTHON-983`_.)
 
 Thus the current design of periodic executors is surprisingly simple: they
-do a simple `time.sleep` for a half-second, check if it is time to wake or
+do a simple ``time.sleep`` for a half-second, check if it is time to wake or
 terminate, and sleep again.
 
 .. _Server Discovery And Monitoring Spec: https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-monitoring.rst#requesting-an-immediate-check
diff --git a/doc/examples/authentication.rst b/doc/examples/authentication.rst
index 5bd3282146..b3ba89026e 100644
--- a/doc/examples/authentication.rst
+++ b/doc/examples/authentication.rst
@@ -180,7 +180,7 @@ URI::
   >>> client = MongoClient(uri)
   >>>
 
-The default service name used by MongoDB and PyMongo is `mongodb`. You can
+The default service name used by MongoDB and PyMongo is ``mongodb``. You can
 specify a custom service name with the ``authMechanismProperties`` option::
 
   >>> from pymongo import MongoClient
diff --git a/doc/examples/datetimes.rst b/doc/examples/datetimes.rst
index f9c9fa7a31..5571880e94 100644
--- a/doc/examples/datetimes.rst
+++ b/doc/examples/datetimes.rst
@@ -37,7 +37,7 @@ time. Avoid doing this:
 
    >>> result = db.objects.insert_one({"last_modified": datetime.datetime.now()})
 
-The value for `last_modified` is very different between these two examples, even
+The value for ``last_modified`` is very different between these two examples, even
 though both documents were stored at around the same local time. This will be
 confusing to the application that reads them:
 
@@ -47,7 +47,7 @@ confusing to the application that reads them:
    [datetime.datetime(2015, 7, 8, 18, 17, 28, 324000),
     datetime.datetime(2015, 7, 8, 11, 17, 42, 911000)]
 
-:class:`bson.codec_options.CodecOptions` has a `tz_aware` option that enables
+:class:`bson.codec_options.CodecOptions` has a ``tz_aware`` option that enables
 "aware" :class:`datetime.datetime` objects, i.e., datetimes that know what
 timezone they're in. By default, PyMongo retrieves naive datetimes:
 
@@ -65,7 +65,7 @@ Saving Datetimes with Timezones
 -------------------------------
 
 When storing :class:`datetime.datetime` objects that specify a timezone
-(i.e. they have a `tzinfo` property that isn't ``None``), PyMongo will convert
+(i.e. they have a ``tzinfo`` property that isn't ``None``), PyMongo will convert
 those datetimes to UTC automatically:
 
 .. doctest::
@@ -82,12 +82,12 @@ Reading Time
 
 As previously mentioned, by default all :class:`datetime.datetime` objects
 returned by PyMongo will be naive but reflect UTC (i.e. the time as stored in
-MongoDB). By setting the `tz_aware` option on
+MongoDB). By setting the ``tz_aware`` option on
 :class:`~bson.codec_options.CodecOptions`, :class:`datetime.datetime` objects
-will be timezone-aware and have a `tzinfo` property that reflects the UTC
+will be timezone-aware and have a ``tzinfo`` property that reflects the UTC
 timezone.
 
-PyMongo 3.1 introduced a `tzinfo` property that can be set on
+PyMongo 3.1 introduced a ``tzinfo`` property that can be set on
 :class:`~bson.codec_options.CodecOptions` to convert :class:`datetime.datetime`
 objects to local time automatically. For example, if we wanted to read all times
 out of MongoDB in US/Pacific time:
@@ -159,7 +159,7 @@ cannot be represented using the builtin Python :class:`~datetime.datetime`:
 :attr:`~bson.datetime_ms.DatetimeConversion.DATETIME_CLAMP` will clamp
 resulting :class:`~datetime.datetime` objects to be within
 :attr:`~datetime.datetime.min` and :attr:`~datetime.datetime.max`
-(trimmed to `999000` microseconds):
+(trimmed to ``999000`` microseconds):
 
 .. doctest::
 
diff --git a/doc/examples/server_selection.rst b/doc/examples/server_selection.rst
index 18de677a58..227e849df3 100644
--- a/doc/examples/server_selection.rst
+++ b/doc/examples/server_selection.rst
@@ -2,7 +2,7 @@ Server Selector Example
 =======================
 
 Users can exert fine-grained control over the `server selection algorithm`_
-by setting the `server_selector` option on the :class:`~pymongo.MongoClient`
+by setting the ``server_selector`` option on the :class:`~pymongo.MongoClient`
 to an appropriate callable. This example shows how to use this functionality
 to prefer servers running on ``localhost``.
 
diff --git a/doc/examples/timeouts.rst b/doc/examples/timeouts.rst
index 73095e5af5..5171588962 100644
--- a/doc/examples/timeouts.rst
+++ b/doc/examples/timeouts.rst
@@ -23,7 +23,7 @@ timeout for an :meth:`~pymongo.collection.Collection.insert_one` operation::
       coll.insert_one({"name": "Nunu"})
 
 The :meth:`~pymongo.timeout` applies to all pymongo operations within the block.
-The following example ensures that both the `insert` and the `find` complete
+The following example ensures that both the ``insert`` and the ``find`` complete
 within 10 seconds total, or raise a timeout error::
 
   with pymongo.timeout(10):
diff --git a/doc/examples/type_hints.rst b/doc/examples/type_hints.rst
index 8aaaff81eb..375ad14330 100644
--- a/doc/examples/type_hints.rst
+++ b/doc/examples/type_hints.rst
@@ -117,7 +117,7 @@ These methods automatically add an "_id" field.
 
 This same typing scheme works for all of the insert methods (:meth:`~pymongo.collection.Collection.insert_one`,
 :meth:`~pymongo.collection.Collection.insert_many`, and :meth:`~pymongo.collection.Collection.bulk_write`).
-For `bulk_write` both :class:`~pymongo.operations.InsertOne` and :class:`~pymongo.operations.ReplaceOne` operators are generic.
+For ``bulk_write`` both :class:`~pymongo.operations.InsertOne` and :class:`~pymongo.operations.ReplaceOne` operators are generic.
 
 .. doctest::
   :pyversion: >= 3.8
@@ -139,16 +139,16 @@ Modeling Document Types with TypedDict
 --------------------------------------
 
 You can use :py:class:`~typing.TypedDict` (Python 3.8+) to model structured data.
-As noted above, PyMongo will automatically add an `_id` field if it is not present. This also applies to TypedDict.
+As noted above, PyMongo will automatically add an ``_id`` field if it is not present. This also applies to TypedDict.
 There are three approaches to this:
 
-  1. Do not specify `_id` at all. It will be inserted automatically, and can be retrieved at run-time, but will yield a type-checking error unless explicitly ignored.
+  1. Do not specify ``_id`` at all. It will be inserted automatically, and can be retrieved at run-time, but will yield a type-checking error unless explicitly ignored.
 
-  2. Specify `_id` explicitly. This will mean that every instance of your custom TypedDict class will have to pass a value for `_id`.
+  2. Specify ``_id`` explicitly. This will mean that every instance of your custom TypedDict class will have to pass a value for ``_id``.
 
-  3. Make use of :py:class:`~typing.NotRequired`. This has the flexibility of option 1, but with the ability to access the `_id` field without causing a type-checking error.
+  3. Make use of :py:class:`~typing.NotRequired`. This has the flexibility of option 1, but with the ability to access the ``_id`` field without causing a type-checking error.
 
-Note: to use :py:class:`~typing.TypedDict` and :py:class:`~typing.NotRequired` in earlier versions of Python (<3.8, <3.11), use the `typing_extensions` package.
+Note: to use :py:class:`~typing.TypedDict` and :py:class:`~typing.NotRequired` in earlier versions of Python (<3.8, <3.11), use the ``typing_extensions`` package.
 
 .. doctest:: typed-dict-example
   :pyversion: >= 3.11
diff --git a/doc/faq.rst b/doc/faq.rst
index b9b5bc4b91..2d211c756c 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -125,7 +125,7 @@ drop below the minimum, more sockets are opened until the minimum is reached.
 
 The maximum number of milliseconds that a connection can remain idle in the
 pool before being removed and replaced can be set with ``maxIdleTimeMS``, which
-defaults to `None` (no limit).
+defaults to ``None`` (no limit).
 
 The default configuration for a :class:`~pymongo.mongo_client.MongoClient`
 works for most applications::
@@ -495,9 +495,9 @@ and :class:`~bson.dbref.DBRef`) that are not supported in JSON.
 
 `python-bsonjs <https://pypi.python.org/pypi/python-bsonjs>`_ is a fast
 BSON to MongoDB Extended JSON converter built on top of
-`libbson <https://github.com/mongodb/libbson>`_. `python-bsonjs` does not
+`libbson <https://github.com/mongodb/libbson>`_. ``python-bsonjs`` does not
 depend on PyMongo and can offer a nice performance improvement over
-:mod:`~bson.json_util`. `python-bsonjs` works best with PyMongo when using
+:mod:`~bson.json_util`. ``python-bsonjs`` works best with PyMongo when using
 :class:`~bson.raw_bson.RawBSONDocument`.
 
 Why do I get OverflowError decoding dates stored by another language's driver?
@@ -543,7 +543,7 @@ objects as before:
 For other options, please refer to
 :class:`~bson.codec_options.DatetimeConversion`.
 
-Another option that does not involve setting `datetime_conversion` is to to
+Another option that does not involve setting ``datetime_conversion`` is to to
 filter out documents values outside of the range supported by
 :class:`~datetime.datetime`:
 
diff --git a/doc/migrate-to-pymongo4.rst b/doc/migrate-to-pymongo4.rst
index 19aa87fcd8..35fc922d51 100644
--- a/doc/migrate-to-pymongo4.rst
+++ b/doc/migrate-to-pymongo4.rst
@@ -870,7 +870,7 @@ GridFS changes
 disable_md5 parameter is removed
 ................................
 
-Removed the `disable_md5` option for :class:`~gridfs.GridFSBucket` and
+Removed the ``disable_md5`` option for :class:`~gridfs.GridFSBucket` and
 :class:`~gridfs.GridFS`. GridFS no longer generates checksums.
 Applications that desire a file digest should implement it outside GridFS
 and store it with other file metadata. For example::
diff --git a/tox.ini b/tox.ini
index d54449fe85..6ea3f57ac6 100644
--- a/tox.ini
+++ b/tox.ini
@@ -133,7 +133,7 @@ description = build sphinx docs
 deps =
     -rdoc/docs-requirements.txt
 commands =
-    sphinx-build -E -b html doc ./doc/_build/html
+    sphinx-build -E -W -b html doc ./doc/_build/html
 
 [testenv:doc-test]
 description = run sphinx doc tests