DOCSP-38344: docs cleanup (#2902)

Assorted cleanup tasks

---------

Co-authored-by: Chris Cho <[email protected]>

Author: ccho-mongodb

docs/compatibility.txt

@@ -14,6 +14,9 @@ Compatibility
    :depth: 1
    :class: singlecol
 
+.. meta::
+   :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2
+
 Laravel Compatibility
 ---------------------
 

docs/eloquent-models.txt

@@ -26,7 +26,7 @@ This section contains guidance on how to use Eloquent models in
   between models
 - :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB
   collections by using Laravel migrations
-  
+
 .. toctree::
 
    /eloquent-models/model-class/

docs/eloquent-models/relationships.txt

@@ -90,7 +90,7 @@ method:
    :dedent:
 
 The following sample code shows how to instantiate a model for each class
-and add the relationship between them. Click the :guilabel:`VIEW OUTPUT`
+and add the relationship between them. Click the :guilabel:`{+code-output-label+}`
 button to see the data created by running the code:
 
 .. io-code-block::
@@ -175,7 +175,7 @@ model by using the ``belongsTo()`` method:
    :dedent:
 
 The following sample code shows how to instantiate a model for each class
-and add the relationship between them.  Click the :guilabel:`VIEW OUTPUT`
+and add the relationship between them.  Click the :guilabel:`{+code-output-label+}`
 button to see the data created by running the code:
 
 .. io-code-block::
@@ -275,7 +275,7 @@ using the ``belongsToMany()`` method:
    :dedent:
 
 The following sample code shows how to instantiate a model for each class
-and add the relationship between them. Click the :guilabel:`VIEW OUTPUT`
+and add the relationship between them. Click the :guilabel:`{+code-output-label+}`
 button to see the data created by running the code:
 
 .. io-code-block::
@@ -405,7 +405,7 @@ following ``Cargo`` model class:
 
 The following sample code shows how to create a ``SpaceShip`` model and
 embed multiple ``Cargo`` models and the MongoDB document created by running the
-code. Click the :guilabel:`VIEW OUTPUT` button to see the data created by
+code. Click the :guilabel:`{+code-output-label+}` button to see the data created by
 running the code:
 
 .. io-code-block::
@@ -496,7 +496,7 @@ model by using the ``belongsTo()`` method:
 
 The following sample code shows how to create a ``SpaceShip`` model in
 a MySQL database and related ``Passenger`` models in a MongoDB database as well
-as the data created by running the code. Click the :guilabel:`VIEW OUTPUT` button
+as the data created by running the code. Click the :guilabel:`{+code-output-label+}` button
 to see the data created by running the code:
 
 .. io-code-block::

docs/eloquent-models/schema-builder.txt

@@ -75,8 +75,9 @@ following changes to perform the schema changes on your MongoDB database:
    MongoDB database, update the following setting to make sure the migration
    specifies the correct database:
 
-   - Specify ``mongodb`` in the ``$connection`` field of your migration class
-   - Set ``DB_CONNECTION=mongodb`` in your ``.env`` configuration file
+   - Make sure your ``connections`` array item contains a valid ``mongodb``
+     entry in your ``config/database.php`` file
+   - Specify ``"mongodb"`` in the ``$connection`` field of your migration class
 
 The following example migration class contains the following methods:
 
@@ -166,9 +167,9 @@ fields:
 
 - Single field index on ``mission_type``
 - Compound index on ``launch_location`` and ``launch_date``, specifying a descending sort order on ``launch_date``
-- Unique index on the ``mission_id`` field, specifying the index name "unique_mission_id_idx"
+- Unique index on the ``mission_id`` field, specifying the index name ``"unique_mission_id_idx"``
 
-Click the :guilabel:`VIEW OUTPUT` button to see the indexes created by running
+Click the :guilabel:`{+code-output-label+}` button to see the indexes created by running
 the migration, including the default index on the ``_id`` field:
 
 .. io-code-block::
@@ -207,7 +208,7 @@ You can specify index options when calling an index creation method, such
 as ``index()``, on a ``Blueprint`` instance.
 
 The following migration code shows how to add a collation to an index as an
-index option. Click the :guilabel:`VIEW OUTPUT` button to see the indexes
+index option. Click the :guilabel:`{+code-output-label+}` button to see the indexes
 created by running the migration, including the default index on the ``_id``
 field:
 
@@ -266,7 +267,7 @@ appropriate helper method on the ``Blueprint`` instance and pass the
 index creation details.
 
 The following migration code shows how to create a sparse and a TTL index
-by using the index helpers. Click the :guilabel:`VIEW OUTPUT` button to see
+by using the index helpers. Click the :guilabel:`{+code-output-label+}` button to see
 the indexes created by running the migration, including the default index on
 the ``_id`` field:
 
@@ -297,7 +298,7 @@ You can specify sparse, TTL, and unique indexes on either a single field or
 compound index by specifying them in the index options.
 
 The following migration code shows how to create all three types of indexes
-on a single field. Click the :guilabel:`VIEW OUTPUT` button to see the indexes
+on a single field. Click the :guilabel:`{+code-output-label+}` button to see the indexes
 created by running the migration, including the default index on the ``_id``
 field:
 
@@ -342,7 +343,7 @@ method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the
 geospatial index creation details on the ``Blueprint`` instance.
 
 The following example migration creates a ``2d`` and ``2dsphere`` geospatial
-index on the ``spaceports`` collection. Click the :guilabel:`VIEW OUTPUT`
+index on the ``spaceports`` collection. Click the :guilabel:`{+code-output-label+}`
 button to see the indexes created by running the migration, including the
 default index on the ``_id`` field:
 

docs/fundamentals.txt

@@ -9,7 +9,7 @@ Fundamentals
    :values: reference
 
 .. meta::
-   :keywords: php framework, odm
+   :keywords: php framework, odm, concepts
 
 .. toctree::
    :titlesonly:
@@ -20,7 +20,7 @@ Fundamentals
    /fundamentals/read-operations
    /fundamentals/write-operations
 
-Learn how to use the {+odm-long+} to perform the following tasks:
+Learn more about the following concepts related to the {+odm-long+}:
 
 - :ref:`laravel-fundamentals-connection`
 - :ref:`laravel-db-coll`

docs/fundamentals/connection.txt

@@ -4,6 +4,13 @@
 Connections
 ===========
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: options, deployment, connection behavior
+
 .. toctree::
 
    /fundamentals/connection/connect-to-mongodb

docs/fundamentals/connection/connect-to-mongodb.txt

@@ -78,6 +78,9 @@ options. In the example, we set the following connection options and values:
 - ``maxPoolSize=20``
 - ``w=majority``
 
+To learn more about connection options, see
+:ref:`laravel-fundamentals-connection-options`.
+
 .. _laravel-database-config:
 
 Laravel Database Connection Configuration
@@ -151,11 +154,13 @@ For a MongoDB database connection, you can specify the following details:
 
    * - ``options``
      - Specifies connection options to pass to MongoDB that determine the
-       connection behavior.
+       connection behavior. To learn more about connection options, see
+       :ref:`laravel-connection-auth-options`.
 
    * - ``driverOptions``
-     - Specifies options specific to pass to the MongoDB PHP Library driver
-       that determine the driver behavior for that connection.
+     - Specifies options specific to pass to the {+php-library+} that
+       determine the driver behavior for that connection. To learn more about
+       driver options, see :ref:`laravel-driver-options`.
 
 .. note::
 
@@ -323,6 +328,8 @@ To learn more about setting up a MongoDB replica set, see
 :manual:`Deploy a Replica Set </tutorial/deploy-replica-set/>` in the
 {+server-docs-name+}.
 
+.. _laravel-direct-connection:
+
 Direct Connection
 `````````````````
 

docs/fundamentals/connection/connection-options.txt

@@ -155,7 +155,9 @@ and their default values:
      - Boolean
      - ``false``
      - Specifies whether to directly connect to a single host instead of
-       discovering and connecting to all servers in the cluster.
+       discovering and connecting to all servers in the cluster. To learn more
+       about this setting, see :ref:`laravel-direct-connection` in the
+       Connection Guide.
 
    * - **heartbeatFrequencyMS**
      - Integer greater than or equal to ``500``
@@ -295,7 +297,7 @@ and their default values:
      - | Requests acknowledgment that the operation has propagated to a
          specific number or variety of servers.
        | To learn more, see :manual:`Write Concern </reference/write-concern>`
-         in the Server manual.
+         in the {+server-docs-name+}.
 
    * - **wTimeoutMS**
      - Non-negative integer

docs/fundamentals/database-collection.txt

@@ -30,7 +30,7 @@ data as **documents** that contain field-and-value pairs. In
 {+odm-short+}, you can access documents through Eloquent models.
 
 To learn more about the document data format,
-see :manual:`Documents </core/document/>` in the Server manual.
+see :manual:`Documents </core/document/>` in the {+server-docs-name+}.
 
 .. _laravel-access-db:
 
@@ -39,7 +39,7 @@ Specify the Database in a Connection Configuration
 
 You can specify a database name that a connection uses in your
 application's ``config/database.php`` file. The ``connections`` property
-in this file stores all of your database connection information, such as
+in this file stores all your database connection information, such as
 your connection string, database name, and optionally, authentication
 details. After you specify a database connection, you can perform
 database-level operations and access collections that the database
@@ -98,8 +98,8 @@ The following example shows how to specify multiple database connections
 
    The MongoDB PHP driver reuses the same connection when
    you create two clients with the same connection string. There is no
-   overhead in using two connections for two distinct databases, so you
-   do not need to optimize your connections.
+   overhead in using two connections for two distinct databases, so it is
+   unnecessary to optimize your connections.
 
 If your application contains multiple database connections and you want
 to store your model in a database other than the default, override the

docs/fundamentals/read-operations.txt

@@ -256,14 +256,14 @@ a text index on the ``plot`` field.
             IMDB Rating: 7.4
             IMDB Votes: 9663
             Plot: A love story between a man and woman ...
-            
+
             Title: Paheli
             Year: 2005
             Runtime: 140
             IMDB Rating: 6.7
             IMDB Votes: 8909
             Plot: A folk tale - supernatural love story about a ghost ...
-            
+
             Title: Por un puèado de besos
             Year: 2014
             Runtime: 98
@@ -296,7 +296,7 @@ results by relevance by using the ``orderBy()`` method to sort on the
 Modify Behavior
 ---------------
 
-You can modify the results of a find operation by chaining additional methods
+You can modify the results of a find operation by chaining more methods
 to ``where()``.
 
 The following sections demonstrate how to modify the behavior of the ``where()``
@@ -397,15 +397,15 @@ followed by the ``orderBy()`` method.
 You can set an **ascending** or **descending** sort direction on
 results. By default, the ``orderBy()`` method sets an ascending sort on
 the supplied field name, but you can explicitly specify an ascending
-sort by passing ``'asc'`` as the second parameter. To
-specify a descending sort, pass ``'desc'`` as the second parameter.
+sort by passing ``"asc"`` as the second parameter. To
+specify a descending sort, pass ``"desc"`` as the second parameter.
 
 If your documents contain duplicate values in a specific field, you can
-handle the tie by specifying additional fields to sort on. This ensures consistent
-results if the additional fields contain unique values.
+handle the tie by specifying more fields to sort on. This ensures consistent
+results if the other fields contain unique values.
 
 This example queries for documents in which the value of the ``countries`` field contains
-``'Indonesia'`` and orders results first by an ascending sort on the
+``"Indonesia"`` and orders results first by an ascending sort on the
 ``year`` field, then a descending sort on the ``title`` field.
 
 .. tabs::
@@ -458,31 +458,31 @@ This example queries for documents in which the value of the ``countries`` field
             IMDB Rating: 7.6
             IMDB Votes: 702
             Plot: A film delivery man promises ...
-            
+
             Title: Gie
             Year: 2005
             Runtime: 147
             IMDB Rating: 7.5
             IMDB Votes: 470
             Plot: Soe Hok Gie is an activist who lived in the sixties ...
-            
+
             Title: Requiem from Java
             Year: 2006
             Runtime: 120
             IMDB Rating: 6.6
             IMDB Votes: 316
             Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi)
             are young married couple ...
-            
+
             ...
 
 .. tip::
 
    To learn more about sorting, see the following resources:
 
    - :manual:`Natural order </reference/glossary/#std-term-natural-order>`
-     in the Server manual glossary
-   - `Ordering, Grouping, Limit and Offset <https://laravel.com/docs/queries#ordering-grouping-limit-and-offset>`__
+     in the {+server-docs-name+} glossary
+   - `Ordering, Grouping, Limit, and Offset <https://laravel.com/docs/queries#ordering-grouping-limit-and-offset>`__
      in the Laravel documentation
 
 .. _laravel-retrieve-one:

docs/fundamentals/write-operations.txt

@@ -283,7 +283,7 @@ Upsert Example
 
 This example shows how to pass the ``upsert`` option to the  ``update()``
 method to perform an update or insert in a single operation. Click the
-:guilabel:`VIEW OUTPUT` button to see the example document inserted when no
+:guilabel:`{+code-output-label+}` button to see the example document inserted when no
 matching documents exist:
 
 .. io-code-block::
@@ -353,7 +353,7 @@ method call:
 
 The following example shows how to add the value ``"baroque"`` to
 the ``genres`` array field of a matching document. Click the
-:guilabel:`VIEW OUTPUT` button to see the updated document:
+:guilabel:`{+code-output-label+}` button to see the updated document:
 
 .. io-code-block::
 
@@ -400,7 +400,7 @@ from the array. The following code example shows the structure of a
 
 The following example shows how to remove array values ``"classical"`` and
 ``"dance-pop"`` from the ``genres`` array field. Click the
-:guilabel:`VIEW OUTPUT` button to see the updated document:
+:guilabel:`{+code-output-label+}` button to see the updated document:
 
 .. io-code-block::
 
@@ -451,7 +451,7 @@ structure of a positional operator update call on a single matching document:
 
 The following example shows how to replace the array value ``"dance-pop"``
 with ``"contemporary"`` in the ``genres`` array field. Click the
-:guilabel:`VIEW OUTPUT` button to see the updated document:
+:guilabel:`{+code-output-label+}` button to see the updated document:
 
 .. io-code-block::
 

docs/includes/query-builder/QueryBuilderTest.php

@@ -228,7 +228,6 @@ public function testAggAvg(): void
         // begin aggregation avg
         $result = DB::collection('movies')
             ->avg('imdb.rating');
-            //->avg('year');
         // end aggregation avg
 
         $this->assertIsFloat($result);

docs/includes/usage-examples/fact-edit-laravel-app.rst

@@ -0,0 +1,2 @@
+To learn how to edit your Laravel application to run the usage example, see the
+:ref:`Usage Examples landing page <laravel-usage-examples>`.

docs/includes/usage-examples/operation-description.rst

@@ -0,0 +1,2 @@
+|operator-description| by creating a query builder, using a method such
+as ``Model::where()`` or the ``DB`` facade to match documents in a collection, and then calling |result-operation|.

docs/index.txt

@@ -1,5 +1,5 @@
 ===============
-Laravel MongoDB
+{+odm-short+}
 ===============
 
 .. facet::
@@ -92,7 +92,6 @@ compatible, see the :ref:`laravel-compatibility` section.
 Upgrade Versions
 ----------------
 
-Learn what changes you might need to make to your application to upgrade
-versions in the :ref:`laravel-upgrading` section.
-
+Learn what changes you must make to your application to upgrade versions in
+the :ref:`laravel-upgrading` section.