Merge 4.1 into 4.2

docs/index.txt

@@ -14,6 +14,7 @@ Laravel MongoDB
    :maxdepth: 1
 
    /quick-start
+   /usage-examples
    Release Notes <https://github.com/mongodb/laravel-mongodb/releases/>
    /retrieve
    /eloquent-models
@@ -47,10 +48,16 @@ Learn how to add {+odm-short+} to a Laravel web application, connect to
 MongoDB hosted on MongoDB Atlas, and begin working with data in the
 :ref:`laravel-quick-start` section.
 
+Usage Examples
+--------------
+
+See fully runnable code examples and explanations of common
+MongoDB operations in the :ref:`laravel-usage-examples` section.
+
 Fundamentals
 ------------
 
-To learn how to perform the following tasks by using the {+odm-short+},
+To learn how to perform the following tasks by using {+odm-short+},
 see the following content:
 
 - :ref:`laravel-fundamentals-retrieve`

docs/quick-start/view-data.txt

@@ -1,4 +1,4 @@
-.. laravel-quick-start-view-data:
+.. _laravel-quick-start-view-data:
 
 =================
 View MongoDB Data

docs/usage-examples.txt

@@ -0,0 +1,68 @@
+.. _laravel-usage-examples:
+
+==============
+Usage Examples
+==============
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: set up, runnable
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+Usage examples show runnable code examples to demonstrate frequently used MongoDB
+operations. Each usage example includes the following components:
+
+- Explanation of the MongoDB operation
+- Example code that you can run from an application controller
+- Output displayed by the print statement
+
+How to Use the Usage Examples
+-----------------------------
+
+To learn how to add a usage example to your Laravel application and view the expected output,
+see the following sections:
+
+- :ref:`before-start`
+- :ref:`run-usage-examples`
+
+.. _before-start:
+
+Before You Get Started
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can run the usage examples from your own Laravel application or from the
+``{+quickstart-app-name+}`` application created in the :ref:`laravel-quick-start` guide. 
+
+The usage examples are designed to run operations on a MongoDB deployment that contains
+the MongoDB Atlas sample datasets. Before running the usage examples, ensure that you load
+the sample data into the MongoDB cluster to which your application connects. Otherwise, the
+operation output might not match the text included in the ``{+code-output-label+}`` tab of
+the usage example page.
+
+.. tip:: 
+
+   For instructions on loading the sample data into a MongoDB cluster, see
+   :atlas:`Load Sample Data </sample-data>` in the Atlas documentation. 
+
+.. _run-usage-examples:
+
+Run the Usage Example
+~~~~~~~~~~~~~~~~~~~~~
+
+Each usage example page includes sample code that demonstrates a MongoDB operation and prints
+a result. To run the operation, you can copy the sample code to a controller endpoint in your
+Laravel application.
+
+To view the expected output of the operation, you can add a web route to your application that
+calls the controller function and returns the result to a web interface.

phpunit.xml.dist

@@ -12,6 +12,9 @@
         <testsuite name="Test Suite">
             <directory>tests/</directory>
         </testsuite>
+        <testsuite name="Documentation">
+            <directory>docs/includes/</directory>
+        </testsuite>
     </testsuites>
     <php>
         <env name="MONGODB_URI" value="mongodb://mongodb/"/>