DOCSP-37618: Usage Examples landing page

docs/index.txt

@@ -14,6 +14,7 @@ Laravel MongoDB
    :maxdepth: 1
 
    /quick-start
+   /usage-examples
    /retrieve
    /eloquent-models
    /query-builder
@@ -46,10 +47,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/usage-examples.txt

@@ -0,0 +1,93 @@
+.. _laravel-usage-examples:
+
+==============
+Usage Examples
+==============
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: set up, runnable, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. TODO: add usage examples to TOC as they're made
+   .. toctree::
+
+
+Overview
+--------
+
+Usage examples show runnable code examples to demonstrate frequently used MongoDB
+operations. Each usage example includes the following:
+
+- Description of the MongoDB operation
+- Code example that runs the MongoDB operation, which you can paste into your controller file
+- Code example that specifies a view, which you can paste into your view file
+- Output returned by the view
+
+How to Use the Usage Examples
+-----------------------------
+
+The usage examples are designed to run operations on a MongoDB deployment that contains
+the Atlas sample datasets. When you run the example code without the sample data, the output
+might not match. 
+
+Follow this tutorial to set up your MongoDB deployment with the sample data and run the
+example code in your development environment. Before performing the following actions,
+ensure that you create an Atlas account and deploy a cluster. For information about setting
+up an account and a cluster, see the :atlas:`Get Started with Atlas Guide
+</getting-started/#atlas-getting-started>`.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a Laravel Application
+
+      Follow the instructions in the :ref:`laravel-quick-start` guide to set up
+      a Laravel application.
+
+      After completing the Quick Start, ensure that your application meets the following
+      requirements:
+
+      - Connects to the ``movies`` collection in the Atlas sample datasets
+      - Contains the ``MovieController.php`` and ``browse_movies.blade.php`` files
+
+   .. step:: Add the Usage Example Code to Your Application
+
+      Copy the example code from the :guilabel:`Controller File Code` tab on the usage example
+      page and paste it into the ``MovieController.php`` file.
+
+      Then, copy the example code from the :guilabel:`View File Code` tab and paste it into the
+      ``browse_movies.blade.php`` file.
+
+   .. step:: Run the Usage Example Code
+
+      Run the following command to start your Laravel application and run the MongoDB operation:
+
+      .. code-block:: bash
+
+         php artisan serve
+
+After completing these steps, you can see the output described in the **Expected Output** section
+of the corresponding usage example.
+
+.. TODO: add usage examples to list as they're made
+   Available Usage Examples
+   ------------------------
+  - :ref:`Find a Document <laravel-find-one-usage>`
+  - :ref:`Find Multiple Documents <laravel-find-usage>`
+  - :ref:`Insert a Document <laravel-insert-one-usage>`
+  - :ref:`Insert Multiple Documents <laravel-insert-many-usage>`
+  - :ref:`Update a Document <laravel-update-one-usage>`
+  - :ref:`Update Multiple Documents <laravel-update-many-usage>`
+  - :ref:`Delete a Document <laravel-delete-one-usage>`
+  - :ref:`Delete Multiple Documents <laravel-delete-many-usage>`
+  - :ref:`Count Documents <laravel-count-usage>`
+  - :ref:`Retrieve Distinct Field Values <laravel-distinct-usage>`