organizing examples section (#30)

Author: nathan-contino-mongo

source/crud.txt

@@ -158,7 +158,7 @@ Update / Replace
 If you want to alter existing documents in a collection, you can use
 :doc:`updateOne() </usage-examples/updateOne>`,
 :doc:`replaceOne() </usage-examples/replaceOne>`, or
-``updateMany()``. These methods
+:doc:`updateMany() </usage-examples/updateMany>`. These methods
 accept a query document that describes the documents you would like to
 change and an :ref:`update document <updateDocument>` that describes
 the changes you would like to apply to matched documents.

source/usage-examples.txt

@@ -4,34 +4,46 @@ Usage Examples
 
 .. default-domain:: mongodb
 
-:doc:`bulkWrite </usage-examples/bulkWrite>`
-:doc:`countDocuments and estimatedDocumentCount </usage-examples/count>`
-:doc:`deleteMany </usage-examples/deleteMany>`
-:doc:`insertOne </usage-examples/insertOne>`
-:doc:`deleteOne </usage-examples/deleteOne>`
-:doc:`find </usage-examples/find>`
-:doc:`findOne </usage-examples/findOne>`
-:doc:`insertMany </usage-examples/insertMany>`
-:doc:`updateOne</usage-examples/updateOne>`
-:doc:`updateMany</usage-examples/updateMany>`
-:doc:`replaceOne</usage-examples/replaceOne>`
-:doc:`distinct</usage-examples/distinct>`
-:doc:`command</usage-examples/command>`
+- :doc:`Find a Document </usage-examples/findOne>`
+
+- :doc:`Find Multiple Documents </usage-examples/find>`
+
+- :doc:`Insert a Document </usage-examples/insertOne>`
+
+- :doc:`Insert Multiple Documents </usage-examples/insertMany>`
+
+
+- :doc:`Update a Document</usage-examples/updateOne>`
+
+- :doc:`Replace a Document</usage-examples/replaceOne>`
+
+- :doc:`Update Multiple Documents</usage-examples/updateMany>`
+
+- :doc:`Delete a Document </usage-examples/deleteOne>`
+
+- :doc:`Delete Multiple Documents </usage-examples/deleteMany>`
+
+- :doc:`Count Documents </usage-examples/count>`
+
+- :doc:`Find Distinct Values of a Field </usage-examples/distinct>`
+
+- :doc:`Run a Command </usage-examples/command>`
+
+- :doc:`Perform Bulk Operations </usage-examples/bulkWrite>`
 
 .. toctree::
    :caption: Examples
 
-   /usage-examples/bulkWrite
-   /usage-examples/count
-   /usage-examples/deleteMany
-   /usage-examples/deleteOne
-   /usage-examples/insertOne
-   /usage-examples/find
    /usage-examples/findOne
-   /usage-examples/findOneAndUpdate
+   /usage-examples/find
+   /usage-examples/insertOne
    /usage-examples/insertMany
    /usage-examples/updateOne
-   /usage-examples/updateMany
    /usage-examples/replaceOne
+   /usage-examples/updateMany
+   /usage-examples/deleteOne
+   /usage-examples/deleteMany
+   /usage-examples/count
    /usage-examples/distinct
    /usage-examples/command
+   /usage-examples/bulkWrite

source/usage-examples/command.txt

@@ -1,31 +1,34 @@
 =============
-Run A Command
+Run a Command
 =============
 
 .. default-domain:: mongodb
 
 Overview
 --------
 
-You can run all raw database operations, not including :manual:`CRUD </crud/>`
-operations, using the :node-api:`command() </Admin.html#~command>`
-method. Typically ``command()`` is used for diagnostic and
-administrative tasks, such as fetching server stats or initializing a
-replica set. 
+You can run all raw database operations, not including
+:manual:`CRUD </crud/>` operations, using the :node-api:`command()
+</Admin.html#~command>` method. Typically ``command()`` is used for
+diagnostic and administrative tasks, such as fetching server stats or
+initializing a replica set.
 
 .. note::
-    Use :manual:`collection methods </reference/method/js-collection>` instead of raw db commands whenever possible.
+    Use :manual:`collection methods </reference/method/js-collection>`
+    instead of raw db commands whenever possible.
 
-Create an `Object
-<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`_
-to specify additional options. Set the ``maxTimeMS`` field of this object to state 
-the number of milliseconds to wait before aborting the query.
+Create an :mdn:`Object
+</Web/JavaScript/Reference/Global_Objects/Object>`
+to specify additional options. Set the ``maxTimeMS`` field of this
+object to state  the number of milliseconds to wait before aborting the
+query.
 
-The ``command()`` method returns a `Promise
-<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
-that resolves to an object containing the return object of the operation that was run.
+The ``command()`` method returns a :mdn:`Promise
+</Web/JavaScript/Reference/Global_Objects/Promise>`
+that resolves to an object containing the return object of the operation
+that was run.
 
 
 .. literalinclude:: /code-snippets/usage-examples/command.js
   :language: javascript
-  :linenos:
+  :linenos:

source/usage-examples/count.txt

@@ -1,6 +1,6 @@
-=============================================
-Count the Number of Documents in a Collection
-=============================================
+===============
+Count Documents
+===============
 
 .. default-domain:: mongodb
 

source/usage-examples/deleteMany.txt

@@ -1,6 +1,6 @@
-=====================
-Delete Many Documents
-=====================
+=========================
+Delete Multiple Documents
+=========================
 
 .. default-domain:: mongodb
 

source/usage-examples/deleteOne.txt

@@ -1,6 +1,6 @@
-===================
-Delete One Document
-===================
+=================
+Delete a Document
+=================
 
 .. default-domain:: mongodb
 
@@ -18,23 +18,24 @@ However, only the first matched document is deleted.
 You can define additional query options using the
 ``options`` object passed as the second parameter of the
 ``deleteOne`` method. You can also pass a
-`callback method <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#~deleteWriteOpCallback>`_
+:node-docs:`callback method <api/Collection.html#~deleteWriteOpCallback>`
 as an optional third parameter. For detailed reference documentation, see
-`collection.deleteOne() <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#deleteOne>`_.
+:node-docs:`collection.deleteOne() <api/Collection.html#deleteOne>`.
 
 ``deleteOne()`` behaves in two different ways depending on
 whether or not a callback method is provided:
 
 - if no callback method is provided, ``deleteOne()`` returns a
-  `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
+  :mdn:`Promise </Web/JavaScript/Reference/Global_Objects/Promise>`
   that resolves to an
-  `Object <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`_
+  :mdn:`Object </Web/JavaScript/Reference/Global_Objects/Object>`
 
 - if a callback method is provided, ``deleteOne()`` returns
   nothing, and instead passes the result object or error object to the
   provided callback method
 
-The `result object <http://mongodb.github.io/node-mongodb-native/3.2/api/Collection.html#~deleteWriteOpResult>`_
+The :node-docs:`result object
+<api/Collection.html#~deleteWriteOpResult>`
 contains several keys in the event of a successful execution. You can
 use the ``deletedCount`` key to check the number of documents deleted by
 the operation. Since ``deleteOne()`` can only delete  a single document,
@@ -47,7 +48,8 @@ what caused the operation to fail.
 
   If your application requires the deleted document after deletion,
   consider using the
-  `collection.findOneAndDelete() <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#findOneAndDelete>`_.
+  :node-docs:`collection.findOneAndDelete()
+  <api/Collection.html#findOneAndDelete>`.
   method, which has a similar interface to ``deleteOne()`` but also
   returns the deleted document.
 

source/usage-examples/distinct.txt

@@ -1,40 +1,39 @@
-==========================================
-Distinct Values of a Field in a Collection
-==========================================
+===============================
+Find Distinct Values of a Field
+===============================
 
 .. default-domain:: mongodb
 
-You can retrieve a list of distinct values for a field across a collection
-by using the `distinct()
-<https://mongodb.github.io/node-mongodb-native/3.4/api/Collection.html#distinct>`_
-method. Call the ``distinct()`` method on a Collection object with
-a document field name parameter as a String to produce a list that contains
-one of each of the different values found in the specified document field.
-
-You can specify a document field within an *embedded document* using `dot
-notation
-<https://docs.mongodb.com/manual/core/document/#embedded-documents>`_. If
-you call ``distinct()`` on an document field that contains an array, each
-element of the array is treated as a separate value.
-
-You can provide an optional query document to narrow the set of documents that
-are searched and an optional Object to specify additional query parameters.
-For details on the optional parameters, see the
-`distinct() method in the API documentation
-<https://mongodb.github.io/node-mongodb-native/3.4/api/Collection.html#distinct>`_.
+You can retrieve a list of distinct values for a field across a
+collection by using the :node-docs:`distinct()
+<api/Collection.html#distinct>` method. Call the ``distinct()`` method
+on a Collection object with a document field name parameter as a String
+to produce a list that contains one of each of the different values
+found in the specified document field.
+
+You can specify a document field within an *embedded document* using
+:manual:`dot
+notation </core/document/#embedded-documents>`. If
+you call ``distinct()`` on an document field that contains an array,
+each element of the array is treated as a separate value.
+
+You can provide an optional query document to narrow the set of
+documents that are searched and an optional Object to specify additional
+query parameters. For details on the optional parameters, see the
+:node-docs:`distinct() method in the API documentation
+<api/Collection.html#distinct>`.
 
 The ``distinct()`` method returns a
-`Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
-that resolves to an
-`Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_
-that contains each of the different values. If none of the documents in the
-collection contain the field specified in the method call, it returns an
-empty Array.
+:mdn:`Promise </Web/JavaScript/Reference/Global_Objects/Promise>` that
+resolves to an :mdn:`Array
+</Web/JavaScript/Reference/Global_Objects/Array>` that contains each of
+the different values. If none of the documents in the collection contain
+the field specified in the method call, it returns an empty Array.
 
 If you specify a value for the document field name that is not of type
-String such as a Document, Array, Number, or ``null``, the method does not
-execute and returns a TypeMismatch error with a message that resembles
-the following:
+String such as a Document, Array, Number, or ``null``, the method does
+not execute and returns a TypeMismatch error with a message that
+resembles the following:
 
 ::
 

source/usage-examples/find.txt

@@ -8,7 +8,7 @@ Overview
 --------
 
 You can
-`query <https://docs.mongodb.com/manual/tutorial/query-documents/#read-operations-query-argument>`_
+:doc:`query </crud/query-document>`
 for multiple documents in a collection with ``collection.find()``.
 The ``find()`` method uses a query document that you provide to match
 only the subset of the documents in the collection that match the query.
@@ -17,21 +17,22 @@ MongoDB returns all documents in the collection.
 
 
 You can also define additional query options such as
-`sort <https://docs.mongodb.com/manual/reference/bson-type-comparison-order/index.html>`_
+:doc:`sort </crud/read-operations/sort>`
 and
-`projection <https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/>`_
+:doc:`projection </crud/read-operations/project>`
 to configure the result set. You should specify these options using the
 cursor methods
-`sort() <https://mongodb.github.io/node-mongodb-native/3.3/api/Cursor.html#sort>`_
+:node-docs:`sort() <api/Cursor.html#sort>`
 and
-`project() <https://mongodb.github.io/node-mongodb-native/3.3/api/Cursor.html#project>`_.
+:node-docs:`project() <api/Cursor.html#project>`.
 For detailed reference documentation, see
-`collection.find() <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#find>`_.
+:node-docs:`collection.find() <api/Collection.html#find>`.
 
 ``find()`` returns a
-`Cursor <https://mongodb.github.io/node-mongodb-native/3.3/api/Cursor.html>`_
-that provides the results of your query. Iterate through the cursor
-using cursor methods like ``next()``, ``toArray()``, or ``forEach()`` to
+:node-api:`Cursor <api/Cursor.html>`
+that provides the results of your query. Iterate through the
+:doc:`cursor </crud/read-operations/cursor>` using cursor methods like
+``next()``, ``toArray()``, or ``forEach()`` to
 fetch and work with the returned documents. If no documents match the
 query, ``find()`` returns an empty cursor.
 

source/usage-examples/findOne.txt

@@ -1,6 +1,6 @@
-=================
-Find One Document
-=================
+===============
+Find a Document
+===============
 
 .. default-domain:: mongodb
 
@@ -49,7 +49,7 @@ collection. It uses the following:
   returned documents and explicitly includes only the ``title`` and
   ``imdb`` object (and its embedded fields).
 
-.. literalinclude:: /code-snippets/usage-examples/find.js
+.. literalinclude:: /code-snippets/usage-examples/findOne.js
   :language: javascript
   :emphasize-lines: 26
   :linenos:

source/usage-examples/insertMany.txt

@@ -1,10 +1,10 @@
-=====================
-Create Many Documents
-=====================
+=========================
+Insert Multiple Documents
+=========================
 
 .. default-domain:: mongodb
 
-You can create multiple documents using the `insertMany()
+You can insert multiple documents using the `insertMany()
 <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#insertMany>`_
 method. The ``insertMany()`` takes an array of documents to insert into
 the specified collection.