diff --git a/docs/index.txt b/docs/index.txt index febdb9371..ec6825419 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -14,6 +14,7 @@ Laravel MongoDB :maxdepth: 1 /quick-start + /usage-examples Release Notes /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` diff --git a/docs/quick-start/view-data.txt b/docs/quick-start/view-data.txt index 35d53368c..1be17bb3f 100644 --- a/docs/quick-start/view-data.txt +++ b/docs/quick-start/view-data.txt @@ -1,4 +1,4 @@ -.. laravel-quick-start-view-data: +.. _laravel-quick-start-view-data: ================= View MongoDB Data diff --git a/docs/usage-examples.txt b/docs/usage-examples.txt new file mode 100644 index 000000000..bf14bba4a --- /dev/null +++ b/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 ` 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. \ No newline at end of file