diff --git a/docs/contribute.txt b/docs/contribute.txt index d25dda4e8d..a541b15fad 100644 --- a/docs/contribute.txt +++ b/docs/contribute.txt @@ -58,7 +58,7 @@ Contribute Code The MongoDB Ruby driver source is located `at GitHub `_. -The list of known issues in the driver is available +The list of known issues in the driver is available `in JIRA `_. 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 `. +readme `__. The driver is tested on `Evergreen `_, MongoDB's in-house continuous integration platform. After a pull request diff --git a/docs/reference/client-side-encryption.txt b/docs/reference/client-side-encryption.txt index 8191c226fb..bfe37d236e 100644 --- a/docs/reference/client-side-encryption.txt +++ b/docs/reference/client-side-encryption.txt @@ -128,12 +128,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 `_. +(versions 4.2 and newer). For installation instructions, see the +`MongoDB manual `_. 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 ` section of this tutorial for more information. Automatic Encryption @@ -274,8 +274,8 @@ The example above demonstrates using automatic encryption with a local master ke For more information about using other key management services 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 ` +- :ref:`Creating A Data Key ` Explicit Encryption =================== @@ -372,8 +372,8 @@ The example above demonstrates using explicit encryption with a local master key For more information about using other key management services 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 ` +- :ref:`Creating A Data Key ` Queryable Encryption ==================== @@ -485,8 +485,8 @@ The example above demonstrates using automatic encryption with a local master ke For more information about using other key management services 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 ` +- :ref:`Creating A Data Key ` Below is an example of explicit queryable encryption. @@ -598,6 +598,7 @@ Below is an example of explicit queryable encryption. find_result = client['encryption_coll'].find(encrypted_field: find_payload).first['encrypted_field'] # => 'sensitive data' +.. _creating-a-master-key: Creating a Master Key ===================== @@ -608,6 +609,8 @@ local key, or by creating a key in a key management service. Currently Ruby driver supports AWS Key Management Service (KMS), Azure Key Vault, and Google Cloud Key Management (GCP KMS). +.. _local-master-key: + Local Master Key ~~~~~~~~~~~~~~~~ @@ -626,17 +629,21 @@ Run the following code to generate a local master key using Ruby: local_master_key = SecureRandom.random_bytes(96) # => "\xB2\xBE\x8EN\xD4\x14\xC2\x13\xC3..." (a binary blob) +.. _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 -:drivers:`"Set up a Remote Master Key" section` +`"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 ` +`Create a Master Key `_ section of the MongoDB manual. +.. _creating-a-data-key: + Creating a Data Key =================== @@ -679,8 +686,8 @@ key with the following code snippet: data_key_id = client_encryption.create_data_key('local') # => -See the `Local Master Key`_ section for more information about generating a new -local master key. +See the :ref:`Local Master Key ` section for more information +about generating a new local master key. Create a Data Key Using a Remote Master Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -788,12 +795,12 @@ certificate and private key to authenticate to KMIP server. ) # => -See the `Remote Master Key`_ section of this tutorial for more information about -generating a new remote master key and finding the information you need to -create data keys. +See the :ref:`Remote Master Key ` section of this tutorial +for more information about generating a new remote master key 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 ` +`Create a Data Encryption Key `_ section of the MongoDB manual. For a list of possible KMS TLS options @@ -974,7 +981,7 @@ When you intend to use your schema map, convert it to a Ruby ``Hash`` using the .. seealso:: - :drivers:`Specify Encrypted Fields Using JSON Schema`, + `Specify Encrypted Fields Using JSON Schema `_, :manual:`Automatic Encryption Rules` .. _schema-map-path: @@ -1012,6 +1019,8 @@ decryption of any previously-encrypted data. } ) +.. _cse-extra-options: + ``:extra_options`` ~~~~~~~~~~~~~~~~~~ diff --git a/docs/reference/connection-and-configuration.txt b/docs/reference/connection-and-configuration.txt index acc28b5250..7532e73f98 100644 --- a/docs/reference/connection-and-configuration.txt +++ b/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 diff --git a/docs/reference/create-client.txt b/docs/reference/create-client.txt index 949f1877cd..5aeb87727c 100644 --- a/docs/reference/create-client.txt +++ b/docs/reference/create-client.txt @@ -903,6 +903,7 @@ URI options are explained in detail in the :manual:`Connection URI reference `. .. note:: + Options that are set in **milliseconds** in the URI are represented as a ``float`` in Ruby and the units are **seconds**. @@ -1348,7 +1349,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 diff --git a/docs/reference/crud-operations.txt b/docs/reference/crud-operations.txt index 73262aa70b..b8e5d5634b 100644 --- a/docs/reference/crud-operations.txt +++ b/docs/reference/crud-operations.txt @@ -988,7 +988,7 @@ for more information on working with these types of fields. 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 diff --git a/docs/reference/gridfs.txt b/docs/reference/gridfs.txt index 267c4b1552..756750b18c 100644 --- a/docs/reference/gridfs.txt +++ b/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 diff --git a/docs/reference/monitoring.txt b/docs/reference/monitoring.txt index 1721feb6a6..b4e1d6c7b1 100644 --- a/docs/reference/monitoring.txt +++ b/docs/reference/monitoring.txt @@ -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 diff --git a/docs/reference/schema-operations.txt b/docs/reference/schema-operations.txt index 713db0afc4..6d3617302a 100644 --- a/docs/reference/schema-operations.txt +++ b/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 diff --git a/docs/reference/working-with-data.txt b/docs/reference/working-with-data.txt index d6d76f82ed..3382428f8e 100644 --- a/docs/reference/working-with-data.txt +++ b/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 diff --git a/docs/release-notes.txt b/docs/release-notes.txt index a4fa945f7b..ece1afdc39 100644 --- a/docs/release-notes.txt +++ b/docs/release-notes.txt @@ -51,7 +51,7 @@ This release includes the following new features: specify an arbitrary comment to help trace the operation through the database profiler, currentOp and logs. - The ``estimated_document_count`` method is now using the ``count`` server - command instead of `$collStats`` aggregation pipeline stage, to support + command instead of ``$collStats`` aggregation pipeline stage, to support operation on views. Applications using the Stable API should upgrade to server versions 5.0.8 (if using MongoDB 5.0) or 5.3.2 (if using MongoDB 5.1/5.2/5.3) or newer to use the ``count`` command when API strict is enabled, diff --git a/docs/tutorials/common-errors.txt b/docs/tutorials/common-errors.txt index 4cb82b9fb6..4151e05b1c 100644 --- a/docs/tutorials/common-errors.txt +++ b/docs/tutorials/common-errors.txt @@ -91,8 +91,10 @@ This error was last reported on Ruby Driver version 2.5.1, so updating the drive can potentially solve this issue. A user has reported that they solved this issue as follows: +.. blockquote:: + DNS servers on EC2 are generated in /etc/resolv.conf by default. Following - the answer `here `_ + the `answer `_ and setting the nameservers to Google NS I was able to fix this issue. You can find more information about this issue here: @@ -116,5 +118,5 @@ authorization mechanism using the ``auth_mech`` option in your ``mongoid.yml`` file. See more on this issue here: -`RUBY-1281 `_. +`RUBY-1684 `_.