Merge cpp-standardization into master (#52)

snooty.toml

@@ -9,8 +9,15 @@ intersphinx = [
 
 toc_landing_pages = [
     "/installation",
-    "/api-abi-versioning"
-    ]
+    "/api-abi-versioning",
+    "/get-started",
+    "/connect",
+    "/read",
+    "/write",
+    "/indexes",
+    "/security",
+    "/data-formats",
+]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
@@ -20,4 +27,8 @@ driver-long = "MongoDB C++ Driver"
 driver-short = "C++ driver"
 version = "3.10"
 full-version = "{+version+}.2"
-api = "https://mongocxx.org/api/current"
+api = "https://mongocxx.org/api/current"
+string-data-type = "``string``"
+int-data-type = "``int``"
+stable-api = "Stable API"
+mdb-server = "MongoDB Server"

source/aggregation.txt

@@ -0,0 +1,195 @@
+.. _cpp-aggregation:
+
+====================================
+Transform Your Data with Aggregation
+====================================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, transform, computed, pipeline
+   :description: Learn how to use the C++ driver to perform aggregation operations.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. TODO:
+ .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    /aggregation/aggregation-tutorials
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+driver-short+} to perform
+**aggregation operations**.
+
+Aggregation operations process data in your MongoDB collections and
+return computed results. The MongoDB Aggregation framework, which is
+part of the Query API, is modeled on the concept of data processing
+pipelines. Documents enter a pipeline that contains one or more stages,
+and this pipeline transforms the documents into an aggregated result.
+
+An aggregation operation is similar to a car factory. A car factory has
+an assembly line, which contains assembly stations with specialized
+tools to do specific jobs, like drills and welders. Raw parts enter the
+factory, and then the assembly line transforms and assembles them into a
+finished product.
+
+The **aggregation pipeline** is the assembly line, **aggregation stages** are the
+assembly stations, and **operator expressions** are the
+specialized tools.
+
+Aggregation Versus Find Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use find operations to perform the following actions:
+
+- Select which documents to return
+- Select which fields to return
+- Sort the results
+
+You can use aggregation operations to perform the following actions:
+
+- Run find operations
+- Rename fields
+- Calculate fields
+- Summarize data
+- Group values
+
+Limitations
+~~~~~~~~~~~
+
+Keep the following limitations in mind when using aggregation operations:
+
+- Returned documents cannot violate the
+  :manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
+  of 16 megabytes.
+- Pipeline stages have a memory limit of 100 megabytes by default. You can exceed this
+  limit by setting the ``allow_disk_use`` field of a ``mongocxx::options::aggregate``
+  instance to ``true``.
+
+.. important:: $graphLookup Exception
+
+   The :manual:`$graphLookup
+   </reference/operator/aggregation/graphLookup/>` stage has a strict
+   memory limit of 100 megabytes and ignores the ``allow_disk_use`` field.
+
+.. _cpp-aggregation-example:
+
+Aggregation Example
+-------------------
+
+.. note::
+
+   The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
+   database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+   free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas
+   </getting-started>` guide.
+
+To perform an aggregation, pass a ``mongocxx::pipeline`` instance containing the aggregation
+stages to the ``collection.aggregate()`` method.
+
+The following code example produces a count of the number of bakeries in each borough
+of New York. To do so, it uses an aggregation pipeline that contains the following stages:
+
+- :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents
+  in which the ``cuisine`` field contains the value ``"Bakery"``
+
+- :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching
+  documents by the ``borough`` field, accumulating a count of documents for each distinct
+  value
+
+.. io-code-block::
+
+   .. input:: /includes/aggregation.cpp
+      :start-after: start-match-group
+      :end-before: end-match-group
+      :language: cpp
+      :dedent:
+
+   .. output:: 
+
+      { "_id" : "Brooklyn", "count" : 173 }
+      { "_id" : "Queens", "count" : 204 }
+      { "_id" : "Bronx", "count" : 71 }
+      { "_id" : "Staten Island", "count" : 20 }
+      { "_id" : "Missing", "count" : 2 }
+      { "_id" : "Manhattan", "count" : 221 }
+
+Explain an Aggregation
+~~~~~~~~~~~~~~~~~~~~~~
+
+To view information about how MongoDB executes your operation, you can
+instruct the MongoDB query planner to **explain** it. When MongoDB explains
+an operation, it returns **execution plans** and performance statistics.
+An execution plan is a potential way MongoDB can complete an operation.
+When you instruct MongoDB to explain an operation, it returns both the
+plan MongoDB executed and any rejected execution plans.
+
+To explain an aggregation operation, run the ``explain`` database command by specifying
+the command in a BSON document and passing it as an argument to the ``run_command()``
+method.
+
+The following example instructs MongoDB to explain the aggregation operation from the
+preceding :ref:`cpp-aggregation-example`:
+
+.. io-code-block::
+
+   .. input:: /includes/aggregation.cpp
+      :start-after: start-explain
+      :end-before: end-explain
+      :language: cpp
+      :dedent:
+
+   .. output:: 
+
+     { "explainVersion" : "2", "queryPlanner" : { "namespace" : "sample_restaurants.restaurants",
+     "indexFilterSet" : false, "parsedQuery" : { "cuisine" : { "$eq" : "Bakery" } }, "queryHash":
+     "...", "planCacheKey" : "...", "optimizedPipeline" : true, "maxIndexedOrSolutionsReached":
+     false, "maxIndexedAndSolutionsReached" : false, "maxScansToExplodeReached" : false,
+     "winningPlan" : { ... } 
+     ... }
+
+
+Additional Information
+----------------------
+
+MongoDB Server Manual
+~~~~~~~~~~~~~~~~~~~~~
+
+To view a full list of expression operators, see :manual:`Aggregation
+Operators. </reference/operator/aggregation/>`
+
+To learn about assembling an aggregation pipeline and view examples, see
+:manual:`Aggregation Pipeline. </core/aggregation-pipeline/>`
+
+To learn more about creating pipeline stages, see :manual:`Aggregation
+Stages. </reference/operator/aggregation-pipeline/>`
+
+To learn more about explaining MongoDB operations, see
+:manual:`Explain Output </reference/explain-results/>` and
+:manual:`Query Plans. </core/query-plans/>`
+
+.. TODO:
+ Aggregation Tutorials
+ ~~~~~~~~~~~~~~~~~~~~~
+
+.. To view step-by-step explanations of common aggregation tasks, see
+.. :ref:`cpp-aggregation-tutorials-landing`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+For more information about executing aggregation operations with the {+driver-short+},
+see the following API documentation:
+
+- `aggregate() <{+api+}/classmongocxx_1_1v__noabi_1_1collection.html#a480f6d0f9986d43b1d17d6ed8876941d>`__
+- `mongocxx::options::aggregate <{+api+}/classmongocxx_1_1v__noabi_1_1options_1_1aggregate.html>`__

source/compatibility.txt

@@ -0,0 +1,45 @@
+.. _cpp-compatibility-tables:
+
+=============
+Compatibility
+=============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: backwards compatibility, versions, upgrade
+
+MongoDB Compatibility
+---------------------
+
+The following compatibility table specifies the recommended version or versions
+of the {+driver-long+} for use with a specific version of MongoDB.
+
+The first column lists the driver version.
+
+.. sharedinclude:: dbx/lifecycle-schedule-callout.rst
+
+.. sharedinclude:: dbx/compatibility-table-legend.rst
+
+.. include:: /includes/mongodb-compatibility-table-cxx.rst
+
+Language Compatibility
+----------------------
+
+The following compatibility table specifies the recommended version of the
+{+driver-long+} for use with a specific version of C++.
+
+The first column lists the driver version.
+
+.. include:: /includes/language-compatibility-table-cxx.rst
+
+For more information on how to read the compatibility tables, see our guide on
+:ref:`MongoDB Compatibility Tables. <about-driver-compatibility>`