PYTHON-4012 Adopt more RST static checks (#1412)

.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

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
 

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

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

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::
 

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``.
 

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):

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

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`:
 

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::

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