move agg tutorials

Author: mongoKart

config/redirects

@@ -70,5 +70,12 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/
 [*-master]: ${prefix}/${version}/indexes/wildcard-index/ -> ${base}/${version}/indexes/
 [*-master]: ${prefix}/${version}/indexes/clustered-index/ -> ${base}/${version}/indexes/
 
+[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/ -> ${base}/${version}/aggregation/
+[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/filtered-subset/ -> ${base}/${version}/aggregation/filtered-subset/
+[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/group-total/ -> ${base}/${version}/aggregation/group-total/
+[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/multi-field-join/ -> ${base}/${version}/aggregation/multi-field-join/
+[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/one-to-one-join/ -> ${base}/${version}/aggregation/one-to-one-join/
+[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/unpack-arrays/ -> ${base}/${version}/aggregation/unpack-arrays/
+
 # temp redirect until DOP deletes unversioned URLs
 [master]: ${prefix}/compatibility/ -> ${base}/current/compatibility/

source/aggregation.txt

@@ -9,7 +9,7 @@ Transform Your Data with Aggregation
    :values: reference
 
 .. meta::
-   :keywords: code example, transform, computed, pipeline
+   :keywords: code example, transform, computed, pipeline, runnable app
    :description: Learn how to use {+driver-short+} to perform aggregation operations.
 
 .. contents:: On this page
@@ -22,7 +22,11 @@ Transform Your Data with Aggregation
    :titlesonly:
    :maxdepth: 1
 
-   Tutorials </aggregation/aggregation-tutorials>
+   Filtered Subset </aggregation/aggregation-tutorials/filtered-subset/>
+   Group & Total </aggregation/aggregation-tutorials/group-total/>
+   Unpack Arrays & Group </aggregation/aggregation-tutorials/unpack-arrays/>
+   One-to-One Join </aggregation/aggregation-tutorials/one-to-one-join/>
+   Multi-Field Join </aggregation/aggregation-tutorials/multi-field-join/>
 
 Overview
 --------
@@ -254,7 +258,36 @@ Aggregation Tutorials
 ~~~~~~~~~~~~~~~~~~~~~
 
 To view step-by-step explanations of common aggregation tasks, see
-:ref:`pymongo-aggregation-tutorials-landing`.
+the following tutorials:
+
+- :ref:`pymongo-aggregation-filtered-subset`
+- :ref:`pymongo-aggregation-group-total`
+- :ref:`pymongo-aggregation-arrays`
+- :ref:`pymongo-aggregation-one-to-one`
+- :ref:`pymongo-aggregation-multi-field`
+
+Aggregation tutorials provide detailed explanations of common
+aggregation tasks in a step-by-step format. The tutorials are adapted
+from examples in the `Practical MongoDB Aggregations book
+<https://www.practical-mongodb-aggregations.com/>`__ by Paul Done.
+
+Each tutorial includes the following sections:
+
+- **Introduction**, which describes the purpose and common use cases of the
+  aggregation type. This section also describes the example and desired
+  outcome that the tutorial demonstrates.
+
+- **Before You Get Started**, which describes the necessary databases,
+  collections, and sample data that you must have before building the
+  aggregation pipeline and performing the aggregation.
+
+- **Tutorial**, which describes how to build and run the aggregation
+  pipeline. This section describes each stage of the completed
+  aggregation tutorial, and then explains how to run and interpret the
+  output of the aggregation.
+
+At the end of each aggregation tutorial, you can find a link to a fully
+runnable Python code file that you can run in your environment.
 
 API Documentation
 ~~~~~~~~~~~~~~~~~

source/aggregation/aggregation-tutorials.txt

@@ -42,9 +42,7 @@ date of birth, vocation, and other details.
 Before You Get Started
 ----------------------
 
-Before you start this tutorial, complete the
-:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working
-Python application.
+.. include:: /includes/aggregation-tutorial-intro.rst
 
 After you set up the app, access the ``persons`` collection by adding the
 following code to the application:

source/aggregation/aggregation-tutorials/filtered-subset.txt renamed to source/aggregation/filtered-subset.txt

@@ -44,9 +44,7 @@ only one customer, the order documents are grouped by the
 Before You Get Started
 ----------------------
 
-Before you start this tutorial, complete the
-:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working
-Python application.
+.. include:: /includes/aggregation-tutorial-intro.rst
 
 After you set up the app, access the ``orders`` collection by adding the
 following code to the application:

source/aggregation/aggregation-tutorials/group-total.txt renamed to source/aggregation/group-total.txt

@@ -66,9 +66,7 @@ the ``orders`` collection.
 Before You Get Started
 ----------------------
 
-Before you start this tutorial, complete the
-:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working
-Python application.
+.. include:: /includes/aggregation-tutorial-intro.rst
 
 After you set up the app, access the ``products`` and ``orders``
 collections by adding the following code to the application:

source/aggregation/aggregation-tutorials/multi-field-join.txt renamed to source/aggregation/multi-field-join.txt

@@ -61,9 +61,7 @@ that exists in documents in both collections.
 Before You Get Started
 ----------------------
 
-Before you start this tutorial, complete the
-:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working
-Python application.
+.. include:: /includes/aggregation-tutorial-intro.rst
 
 After you set up the app, access the ``orders`` and ``products``
 collections by adding the following code to the application:

source/aggregation/aggregation-tutorials/one-to-one-join.txt renamed to source/aggregation/one-to-one-join.txt

@@ -46,9 +46,7 @@ into individual product order documents.
 Before You Get Started
 ----------------------
 
-Before you start this tutorial, complete the
-:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working
-Python application.
+.. include:: /includes/aggregation-tutorial-intro.rst
 
 After you set up the app, access the ``orders`` collection by adding the
 following code to the application:

source/aggregation/aggregation-tutorials/unpack-arrays.txt renamed to source/aggregation/unpack-arrays.txt

@@ -0,0 +1,45 @@
+Before you begin following an aggregation tutorial, you must set up a
+new Python app. You can use this app to connect to a MongoDB
+deployment, insert sample data into MongoDB, and run the aggregation
+pipeline in each tutorial.
+
+.. tip:: 
+   
+   To learn how to install the driver and connect to MongoDB,
+   see :ref:`pymongo-get-started`
+
+Once you install the driver, create a file called
+``agg_tutorial.py``. Paste the following code in this file to create an
+app template for the aggregation tutorials:
+
+.. literalinclude:: /includes/aggregation/template-app.py
+   :language: python
+   :copyable: true
+
+.. important::
+
+   In the preceding code, read the code comments to find the sections of
+   the code that you must modify for the tutorial you are following.
+
+   If you attempt to run the code without making any changes, you will
+   encounter a connection error.
+
+For every tutorial, you must replace the connection string placeholder with
+your deployment's connection string. To learn how to locate your deployment's connection
+string, see :ref:`pymongo-get-started-connection-string`.
+
+For example, if your connection string is
+``"mongodb+srv://mongodb-example:27017"``, your connection string assignment resembles
+the following:
+
+.. code-block:: python
+   :copyable: false
+
+   uri = "mongodb+srv://mongodb-example:27017";
+
+To run the completed file after you modify the template for a
+tutorial, run the following command in your shell:
+
+.. code-block:: bash
+
+   python3 agg_tutorial.py