DOCSP-37618: Usage Examples landing page

.github/workflows/merge-up.yml

@@ -5,8 +5,12 @@ on:
     branches:
       - "[0-9]+.[0-9]+"
 
+permissions:
+  contents: write
+  pull-requests: write
+
 env:
-  GH_TOKEN: ${{ secrets.MERGE_UP_TOKEN }}
+  GH_TOKEN: ${{ github.token }}
 
 jobs:
   merge-up:
@@ -20,7 +24,6 @@ jobs:
         with:
           # fetch-depth 0 is required to fetch all branches, not just the branch being built
           fetch-depth: 0
-          token: ${{ secrets.MERGE_UP_TOKEN }}
 
       - name: Create pull request
         id: create-pull-request

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/usage-examples.txt

@@ -0,0 +1,74 @@
+.. _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
+
+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 controller code that runs the MongoDB operation
+- Example view code that renders the result
+- Output displayed by the view
+
+How to Run the Usage Examples
+-----------------------------
+
+To learn how to set up your application and run the usage examples, see the following
+sections:
+
+- :ref:`before-start`
+- :ref:`run-usage-examples`
+
+.. _before-start:
+
+Before You Get Started
+~~~~~~~~~~~~~~~~~~~~~~
+
+The usage examples are designed to run operations on a MongoDB deployment that contains
+the MongoDB Atlas sample datasets. When you run the example code without this sample data,
+the output might not match. 
+
+You can run the usage examples from the Laravel web application and MongoDB Atlas cluster that
+you set up in the :ref:`laravel-quick-start` guide. After completing the Quick Start, ensure
+that your application meets the following requirements:
+
+- Configuration to use an Atlas cluster that contains the sample datasets
+- ``Movie`` model configured to use the MongoDB database
+- ``Movie`` view that lists the results
+- HTTP and API controller endpoints for displaying and storing ``Movie`` data
+
+.. _run-usage-examples:
+
+Run the Examples
+~~~~~~~~~~~~~~~~
+
+Each Usage Example page features example code in the :guilabel:`Controller File Code` and
+:guilabel:`View File Code` tabs that you can copy and paste into your Laravel application.
+
+Unless otherwise specified, you can add Usage Example sample code to your application by performing
+the following actions:
+
+- Add the code from the :guilabel:`Controller File Code` tab to your ``MovieController.php`` file in the
+  ``app/Http/Controllers`` directory
+- Add the code from the :guilabel:`View File Code` to your ``browse_movies.blade.php`` file in the
+  ``resources/views`` directory.
+
+Follow the instructions on the Usage Example page to run the code and view the expected output.