RUBY-3160 fix all parse errors except bson-tutorials (#2672) (#2764)

Co-authored-by: Neil Shweky <neilshweky@gmail.com>

Author: comandeo-mongo

docs/contribute.txt

@@ -58,7 +58,7 @@ Contribute Code
 The MongoDB Ruby driver source is located
 `at GitHub <https://github.com/mongodb/mongo-ruby-driver>`_.
 
-The list of known issues in the driver is available 
+The list of known issues in the driver is available
 `in JIRA <https://jira.mongodb.org/browse/RUBY>`_.
 
 We recommend creating a JIRA ticket before starting work on a bug fix or
@@ -73,7 +73,7 @@ the changes to the stable branches, if needed.
 A MongoDB deployment is required to run the tests. Setup procedures and
 recommendations for various deployments, as well as how to configure the
 driver's test suite for the deployments, are covered in the `spec
-readme <https://github.com/mongodb/mongo-ruby-driver/blob/master/spec/README.md>`.
+readme <https://github.com/mongodb/mongo-ruby-driver/blob/master/spec/README.md>`__.
 
 The driver is tested on `Evergreen <https://github.com/evergreen-ci/evergreen>`_,
 MongoDB's in-house continuous integration platform. After a pull request

docs/reference/client-side-encryption.txt

@@ -74,12 +74,12 @@ enterprise-only feature. If you only intend to use explicit encryption, you may
 skip this step.
 
 Mongocryptd comes pre-packaged with enterprise builds of the MongoDB server
-(versions 4.2 and newer). For installation instructions, see
-`the MongoDB manual <https://docs.mongodb.com/manual/reference/security-client-side-encryption-appendix/#installation>`_.
+(versions 4.2 and newer). For installation instructions, see the
+`MongoDB manual <https://mongodb.com/docs/manual/reference/security-client-side-encryption-appendix/#installation>`_.
 
 In order to configure mongocryptd (for example, which port it listens on or the
 path used to spawn the daemon), it is necessary to pass different options to the
-``Mongo::Client`` performing automatic encryption. See the `:extra_options`_
+``Mongo::Client`` performing automatic encryption. See the :ref:`:extra_options <cse-extra-options>`
 section of this tutorial for more information.
 
 Automatic Encryption
@@ -202,11 +202,12 @@ The example above demonstrates using automatic encryption with a local master ke
 For more information about using the AWS Key Management Service to create a
 master key and create data keys, see the following sections of this tutorial:
 
-- `Creating A Master Key`_
-- `Creating A Data Key`_
+- :ref:`Creating A Master Key <creating-a-master-key>`
+- :ref:`Creating A Data Key <creating-a-data-key>`
 
 Explicit Encryption
 ===================
+
 Explicit encryption is a feature that allows users to encrypt and decrypt
 individual pieces of data such as strings, integers, or symbols. Explicit
 encryption is a community feature and does not require an enterprise build
@@ -296,8 +297,8 @@ The example above demonstrates using explicit encryption with a local master key
 For more information about using the AWS Key Management Service to create a
 master key and create data keys, see the following sections of this tutorial:
 
-- `Creating A Master Key`_,
-- `Creating A Data Key`_,
+- :ref:`Creating A Master Key <creating-a-master-key>`
+- :ref:`Creating A Data Key <creating-a-data-key>`
 
 Creating a Master Key
 =====================
@@ -307,8 +308,11 @@ user data. The master key can be generated in one of two ways: by creating a
 local key, or by creating a key in the Amazon Web Services Key Management
 Service (AWS KMS).
 
+.. _local-master-key:
+
 Local Master Key
 ~~~~~~~~~~~~~~~~
+
 A local master key is a 96-byte binary string. It should be persisted
 on your machine as an environment variable or in a text file.
 
@@ -329,14 +333,25 @@ AWS Master Key
 It is recommended that you use Amazon's Key Management Service to create and
 store your master key. To do so, follow steps 1 and 2 of the
 :drivers:`"Convert to a Remote Master Key" section</security/client-side-field-level-encryption-local-key-to-kms/#convert-to-a-remote-master-key>`
+.. _remote-master-key:
+
+Remote Master Key
+~~~~~~~~~~~~~~~~~
+It is recommended that you use a remote Key Management Service to create and
+store your master key. To do so, follow steps of the
+`"Set up a Remote Master Key" <https://www.mongodb.com/docs/manual/core/csfle/tutorials/#set-up-a-remote-master-key>`_
 in the MongoDB Client-Side Encryption documentation.
 
 For more information about creating a master key, see the
 :drivers:`Create a Master Key </security/client-side-field-level-encryption-guide/#a-create-a-master-key>`
+`Create a Master Key <https://www.mongodb.com/docs/manual/core/csfle/#a.-create-a-master-key>`_
 section of the MongoDB manual.
 
+.. _creating-a-data-key:
+
 Creating a Data Key
 ===================
+
 Once you have created a master key, create a data key by calling the
 ``#create_data_key`` method on an instance of the ``Mongo::ClientEncryption``
 class. This method generates a new data key and inserts it into the key vault
@@ -376,8 +391,8 @@ key with the following code snippet:
   data_key_id = client_encryption.create_data_key('local')
   # => <BSON::Binary... type=ciphertext...>
 
-See the `Local Master Key`_ section for more information about generating a new
-local master key.
+See the :ref:`Local Master Key <local-master-key>` section for more information
+about generating a new local master key.
 
 Create a Data Key Using an AWS Master Key
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -423,18 +438,20 @@ generating a new master key on AWS and finding the information you need to
 create data keys.
 
 For more information about creating a data key, see the
-:drivers:`Create a Data Encryption Key </security/client-side-field-level-encryption-guide/#b-create-a-data-encryption-key>`
+`Create a Data Encryption Key <https://www.mongodb.com/docs/manual/core/csfle/#b.-create-a-data-encryption-key>`_
 section of the MongoDB manual.
 
 Auto-Encryption Options
 =======================
+
 Automatic encryption can be configured on a ``Mongo::Client`` using the
 ``auto_encryption_options`` option ``Hash``. This section provides an overview
 of the fields inside ``auto_encryption_options`` and explains how to choose their
 values.
 
 ``:key_vault_client``
 ~~~~~~~~~~~~~~~~~~~~~
+
 The key vault client is a ``Mongo::Client`` instance that will be used to connect
 to the MongoDB collection containing your encryption data keys. For example, if
 your key vault was hosted on a MongoDB instance at ``localhost:30000``:
@@ -456,6 +473,7 @@ to insert and fetch data keys.
 
 ``:key_vault_namespace``
 ~~~~~~~~~~~~~~~~~~~~~~~~
+
 The key vault namespace is a ``String`` in the format ``"database_name.collection_name"``,
 where ``database_name`` and ``collection_name`` are the name of the database and
 collection in which you would like to store your data keys. For example, if your data
@@ -474,6 +492,7 @@ There is no default key vault namespace, and this option must be provided.
 
 ``:schema_map``
 ~~~~~~~~~~~~~~~
+
 A schema map is a Hash with information about which fields to automatically
 encrypt and decrypt.
 
@@ -549,11 +568,12 @@ When you intend to use your schema map, convert it to a Ruby ``Hash`` using the
 
 .. seealso::
 
-  :drivers:`Specify Encrypted Fields Using JSON Schema</security/client-side-field-level-encryption-guide/#c-specify-encrypted-fields-using-json-schema>`,
+  `Specify Encrypted Fields Using JSON Schema <https://www.mongodb.com/docs/manual/core/csfle/#c-specify-encrypted-fields-using-json-schema>`_,
   :manual:`Automatic Encryption Rules</reference/security-client-side-automatic-json-schema/>`
 
 ``:bypass_auto_encryption``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The ``:bypass_auto_encryption`` option is a ``Boolean`` that specifies whether the
 ``Mongo::Client`` should skip encryption when writing to the database. If
 ``:bypass_auto_encryption`` is ``true``, the client will still perform automatic
@@ -568,8 +588,11 @@ decryption of any previously-encrypted data.
     }
   )
 
+.. _cse-extra-options:
+
 ``:extra_options``
 ~~~~~~~~~~~~~~~~~~
+
 ``:extra_options`` is a ``Hash`` of options related to spawning mongocryptd.
 Every option in this ``Hash`` has a default value, so it is only necessary to
 provide the options whose defaults you want to override.

docs/reference/connection-and-configuration.txt

@@ -12,7 +12,7 @@ options the driver provides, including authentication.
 .. toctree::
   :titlesonly:
 
-  create-client
-  authentication
-  monitoring
-  user-management
+  /reference/create-client
+  /reference/authentication
+  /reference/monitoring
+  /reference/user-management

docs/reference/create-client.txt

@@ -882,6 +882,7 @@ URI options are explained in detail in the :manual:`Connection URI reference
 </reference/connection-string/>`.
 
 .. note::
+
   Options that are set in **milliseconds** in the URI are
   represented as a ``float`` in Ruby and the units are **seconds**.
 
@@ -1321,7 +1322,7 @@ It is also possible to remove hooks from ``Mongo.tls_context_hooks`` by storing
 a reference to the Procs somewhere else in the application, and then using
 ``Array#delete_if`` to remove the desired hooks.
 
-..warning ::
+.. warning::
 
   TLS context hooks are global and will affect every instance of ``Mongo::Client``.
   Any library that allows applications to enable these hooks should expose methods to

docs/reference/crud-operations.txt

@@ -967,7 +967,7 @@ underscore one that Ruby driver uses.
 A Note about the BSON Symbol type
 =================================
 
-Because the BSON specification deprecated the BSON symbol type, the `bson` gem
+Because the BSON specification deprecated the BSON symbol type, the ``bson`` gem
 will serialize Ruby symbols into BSON strings when used on its own. However, in
 order to maintain backwards compatibility with older datasets, the Ruby driver
 overrides this behavior to serialize Ruby symbols as BSON symbols. This is

docs/reference/gridfs.txt

@@ -252,7 +252,7 @@ by default into the ``fs.chunks`` collection and file metadata is inserted into
 
   client.database.fs.insert_one(file)
 
-To insert into collections with a name prefix other than `fs`, access the
+To insert into collections with a name prefix other than ``fs``, access the
 filesystem with a ``:fs_name`` option.
 
 .. code-block:: ruby

docs/reference/monitoring.txt

@@ -137,35 +137,35 @@ can look like the following:
       format("SDAM | %s".freeze, message)
     end
   end
-  
+
   class TopologyOpeningLogSubscriber < SDAMLogSubscriber
     private
-    
+
     def format_event(event)
       "Topology type '#{event.topology.display_name}' initializing."
     end
   end
-  
+
   class ServerOpeningLogSubscriber < SDAMLogSubscriber
     private
-    
+
     def format_event(event)
       "Server #{event.address} initializing."
     end
   end
-  
+
   class ServerDescriptionChangedLogSubscriber < SDAMLogSubscriber
     private
-    
+
     def format_event(event)
       "Server description for #{event.address} changed from " +
       "'#{event.previous_description.server_type}' to '#{event.new_description.server_type}'."
     end
   end
-  
+
   class TopologyChangedLogSubscriber < SDAMLogSubscriber
     private
-    
+
     def format_event(event)
       if event.previous_topology != event.new_topology
         "Topology type '#{event.previous_topology.display_name}' changed to " +
@@ -176,18 +176,18 @@ can look like the following:
       end
     end
   end
-  
+
   class ServerClosedLogSubscriber < SDAMLogSubscriber
     private
-    
+
     def format_event(event)
       "Server #{event.address} connection closed."
     end
   end
-  
+
   class TopologyClosedLogSubscriber < SDAMLogSubscriber
     private
-    
+
     def format_event(event)
       "Topology type '#{event.topology.display_name}' closed."
     end
@@ -228,7 +228,7 @@ since the events may be published during the client's construction:
   topology_changed_subscriber = TopologyChangedLogSubscriber.new
   server_closed_subscriber = ServerClosedLogSubscriber.new
   topology_closed_subscriber = TopologyClosedLogSubscriber.new
-  
+
   sdam_proc = Proc.new do |client|
     client.subscribe(Mongo::Monitoring::TOPOLOGY_OPENING,
       topology_opening_subscriber)
@@ -287,9 +287,9 @@ Server Heartbeats
 
 The application can be notified of each server heartbeat by subscribing
 to SERVER_HEARTBEAT topic. A server heartbeat listener must implement
-three methods: `started`, `succeeded` and `failed`. Each heartbeat invokes
-the `started` method on the listener, and then either `succeeded` or `failed`
-method depending on the outcome of the heartbeat.
+three methods: ``started``, ``succeeded`` and ``failed``. Each heartbeat
+invokes the ``started`` method on the listener, and then either ``succeeded``
+or ``failed`` method depending on the outcome of the heartbeat.
 
 All heartbeat events contain the address of the server that the heartbeat
 was sent to. Succeeded and failed events contain the round trip time for
@@ -316,9 +316,9 @@ The following is an example logging heartbeat event subscriber:
     def failed(event)
       log_debug("#{event.address} | FAILED | #{event.error.class}: #{event.error.message} | #{event.duration}s")
     end
-    
+
     private
-    
+
     def logger
       Mongo::Logger.logger
     end

docs/reference/schema-operations.txt

@@ -12,7 +12,7 @@ including managing databases, collections, indexes and users.
 .. toctree::
   :titlesonly:
 
-  database-tasks
-  collection-tasks
-  indexing
-  collations
+  /reference/database-tasks
+  /reference/collection-tasks
+  /reference/indexing
+  /reference/collations

docs/reference/working-with-data.txt

@@ -12,16 +12,16 @@ implements for inserting, updating and retrieving data from MongoDB.
 .. toctree::
   :titlesonly:
 
-  crud-operations
-  bulk-operations
-  projection
-  aggregation
-  map-reduce
-  text-search
-  geospatial-search
-  query-cache
-  gridfs
-  change-streams
-  sessions
-  transactions
-  client-side-encryption
+  /reference/crud-operations
+  /reference/bulk-operations
+  /reference/projection
+  /reference/aggregation
+  /reference/map-reduce
+  /reference/text-search
+  /reference/geospatial-search
+  /reference/query-cache
+  /reference/gridfs
+  /reference/change-streams
+  /reference/sessions
+  /reference/transactions
+  /reference/client-side-encryption