(DOCSP-32028): Switch to a PLP and provide info about using mongosh with Atlas (#299)

* Switch to a product landing page

* Add images

* Tweak mongosh styling

* Use procedures in tabs

* Snooty is upset with me

* Remove procedures to debug

* Add connect procedure

* Tweak the connect procedure

* Start adding CRUD details. Build to check Snooty.

* Build out CRUD and agg procedure

* Add info about administering and managing

* Add info about writing scripts

* Minor tweaks

* Fix a ref

* Remove install CTA

* Switch Atlas link to an extlink

* Incorporate review feedback

* Fix example

* From comfort to convenience

* Apply suggestions from review

Co-authored-by: Sarah Simpers <[email protected]>

* Incorporate wording improvements

* Incorporate suggestions

Co-authored-by: Alison Huh <[email protected]>

* Make the card CTA title case for consistency

---------

Co-authored-by: Sarah Simpers <[email protected]>
Co-authored-by: Alison Huh <[email protected]>

Author: 3 people

source/images/mongosh-plp/Technical_ACTION_SearchDocument_Thumbnail_BS_Mist.png

@@ -1,80 +1,263 @@
+:template: product-landing
+:hidefeedback: header
+:noprevnext:
+
 .. program:: mongosh
 
 .. binary:: mongosh
 
 .. _mdb-shell-overview:
 
-===========================
-MongoDB Shell (``mongosh``)
-===========================
+======================================
+Welcome to MongoDB Shell (``mongosh``)
+======================================
+
+.. introduction::
+
+   The |mdb-shell|, ``mongosh``, is a JavaScript and Node.js |repl| 
+   environment for interacting with MongoDB deployments in 
+   `Atlas <https://www.mongodb.com/docs/atlas/>`__, locally,
+   or on another remote host. Use the |mdb-shell| to test queries and 
+   interact with the data in your MongoDB database.
+
+   .. button:: Download mongosh
+      :uri: https://www.mongodb.com/try/download/shell?jmp=docs
+
+.. image:: /images/mongosh-plp/Technical_SOFTWARE_Terminal(3)_Spot.png
+   :alt: Abstract illustration showing a terminal interacting with different systems 
+
+.. kicker:: What You Can Do
+
+Access MongoDB From Your Shell
+------------------------------
+
+.. tabs::
+
+   .. tab:: Connect to MongoDB
+      :tabid: connect
+
+      .. procedure::
+
+         .. step:: Find Your Connection String
+
+            Find your connection string. The connection string varies 
+            depending on the type of deployment you're connecting to.
+
+            Learn how to find your connection string for
+            `Atlas <https://www.mongodb.com/docs/manual/reference/connection-string/#find-your-connection-string>`__.
+
+            Or connect to an 
+            `self-hosted <https://www.mongodb.com/docs/manual/reference/connection-string/#find-your-self-hosted-deployment-s-connection-string>`__
+            deployment.
+
+         .. step:: Connect to MongoDB
+
+            Connect to a MongoDB deployment using the
+            connection string. 
+            
+            The following connection string connects to 
+            an Atlas deployment:
+
+            .. code-block:: sh
+
+               mongosh "mongodb+srv://mycluster.abcd1.mongodb.net/myFirstDatabase" --apiVersion 1 --username <username>
+
+         .. step:: Interact with Your Data
+
+            Use your chosen connection type to view your data, import 
+            documents, and run queries.
+
+            For more information, refer to :ref:`mdb-shell-crud`.
+
+      .. image:: /images/mongosh-plp/atlas_plp.gif
+         :alt: MongoDB Atlas Connect to your Database image
+
+   .. tab:: Perform CRUD and Aggregation
+      :tabid: crud
+
+      .. procedure::
+
+         .. step:: Insert Documents
+
+            :binary:`~bin.mongosh` supports common insert opererations, 
+            including:
+
+            - :method:`db.collection.insertOne()`
+            - :method:`db.collection.insertMany()`
+
+            For more information and examples, refer to :ref:`mongosh-insert`.
+
+         .. step:: Read Documents
+
+            Use the :method:`db.collection.find()` method to query documents
+            in a collection. For more information and examples, refer to 
+            :ref:`mongosh-read`.
+
+         .. step:: Update Documents
+
+            :binary:`~bin.mongosh` supports common update operations, 
+            including:
+
+            - :method:`db.collection.updateOne()`
+            - :method:`db.collection.updateMany()`
+            - :method:`db.collection.replaceOne()`
+
+            For more information and examples, refer to :ref:`mongosh-update`.
+
+         .. step:: Delete Documents
+
+            :binary:`~bin.mongosh` supports common delete operations, 
+            including:
+
+            - :method:`db.collection.deleteMany()`
+            - :method:`db.collection.deleteOne()`
+
+            For more information and examples, refer to :ref:`mongosh-delete`.
+
+         .. step:: Run Aggregation Pipelines
+
+            You can run aggregation pipelines in :binary:`~bin.mongosh` 
+            using the :method:`db.collection.aggregate()` method. 
+            Aggregation pipelines transform your documents into 
+            aggregated results based on the stages you specify. For more 
+            information and examples, refer to :ref:`mdb-shell-aggregation`.
+
+      .. image:: /images/mongosh-plp/Technical_ACTION_SearchDocument_Thumbnail_BS_Mist.png
+         :alt: Abstract illustration showing CRUD and aggregation operations
+
+   .. tab:: Administer and Manage
+      :tabid: administer
+
+      .. procedure::
+
+         .. step:: Manage Databases and Collections
+
+            View information about databases, create collections or views,
+            or drop databases - all from your shell. See all 
+            :ref:`Database Methods <mongosh-database-methods>`.
+
+            Perform collection operations, create or delete indexes, or 
+            explain queries with :ref:`Collection Methods 
+            <mongosh-collection-methods>`.
+
+         .. step:: Administer Servers
+
+            Manage :ref:`replication <mongosh-replication-methods>` or 
+            :ref:`sharding <mongosh-sharding-methods>` conveniently in 
+            your shell.
+
+            Check server status with a variety of :ref:`Server Status Methods 
+            <mongosh-server-status-methods>`.
+
+         .. step:: Manage Users and Roles
+
+            Create or update roles, define and update privileges, or drop 
+            roles using :ref:`Role Management Methods 
+            <mongosh-role-management-methods>`.
+
+            Create and update users, authenticate users, and manage user
+            roles with :ref:`User Management Methods 
+            <mongosh-user-management-methods>`. 
+
+      .. image:: /images/mongosh-plp/Technical_SOFTWARE_Terminal(1)_Spot.png
+         :alt: Abstract illustration showing a terminal performing operations
+
+   .. tab:: Automate with Scripts
+      :tabid: scripts
+
+      .. procedure::
+
+         .. step:: Run Scripts for CRUD or Administrative Tasks
+
+            Write scripts to run with the |mdb-shell| that perform CRUD or 
+            administrative operations in MongoDB.
+
+            For example, if you have a JS file that seeds synthetic or
+            mock data into MongoDB in your development or staging 
+            environment, run the file with:
+
+            .. code-block:: sh
+
+               mongosh YOUR_JS_FILENAME.js
+
+            Explore a tutorial that uses the |mdb-shell| with JavaScript to
+            access MongoDB: :ref:`mdb-shell-write-scripts`.
 
-.. default-domain:: mongodb
+         .. step:: Create Custom Helper Functions with .mongoshrc
 
-.. contents:: On this page
-   :local:
-   :backlinks: none
-   :depth: 1
-   :class: singlecol
+            Repeatedly writing large helper functions in the Shell? Store 
+            them in a :ref:`.mongoshrc config file <mongoshrc-js>`. For 
+            example, if you often find yourself converting date strings to 
+            ISO format for queries, create a function in ``.mongoshrc`` to 
+            handle it:
 
-The |mdb-shell|, ``mongosh``, is a fully functional JavaScript and 
-Node.js 16.x |repl| environment for interacting with MongoDB 
-deployments. You can use the |mdb-shell| to test queries and operations 
-directly with your database.
+            .. code-block:: JavaScript
 
-:binary:`~bin.mongosh` is available as a standalone package in the
-`MongoDB Download Center
-<https://www.mongodb.com/try/download/shell?jmp=docs>`__.
+               function toISO(dateString) { 
+                  return new Date(dateString).toISOString(); 
+               }
 
-Download and Install ``mongosh``
---------------------------------
+            Then, call the function in ``mongosh``:
 
-To learn how to download and install the ``mongosh`` binary, see
-:ref:`mdb-shell-install`.
+            .. code-block:: sh
 
-Connect to a MongoDB Deployment
--------------------------------
+               db.clientConnections.find( { connectTime: toISO("06/07/2017") } )
 
-Once you have installed the |mdb-shell| and added it to your system
-``PATH``, you can connect to a MongoDB deployment. To learn more, see
-:ref:`mdb-shell-connect`.
+            For more information, refer to :ref:`mongosh-write-scripts-config-file`.
 
-The |mdb-shell| versus the Legacy ``mongo`` Shell
--------------------------------------------------
+         .. step:: Use or Publish Snippets
 
-The legacy ``mongo`` shell was deprecated in MongoDB 5.0 and removed in
-MongoDB 6.0. The new MongoDB Shell, ``mongosh``, offers numerous
-advantages over the legacy shell. The new shell has improved:
+            :ref:`Pull existing snippets <snip-install-packages>` into 
+            your codebase for convenient reuse. Or :ref:`create and share 
+            snippets <snip-create>` for your custom use case.
 
-- compatibility with the MongoDB `Node.js
-  <https://www.mongodb.com/docs/drivers/node/current/>`__ driver
-- syntax highlighting
-- command history
-- logging
+            For example, you might have a snippet that validates the data
+            you import daily as a cron job. You can publish this snippet, 
+            so your development team can access it. Publish to a community
+            registry or configure a private registry. 
+            
+            For more information, refer to :ref:`snip-reg-config`.
 
-Some legacy methods are unavailable or have been replaced with updated
-methods in ``mongosh``. To maintain backwards compatibility, the legacy
-methods that ``mongosh`` supports use the same syntax as the
-corresponding methods in the ``mongo`` shell. 
+      .. image:: /images/mongosh-plp/Technical_SOFTWARE_Terminal(4)_Spot.png
+         :alt: Abstract illustration implying a terminal executing scripts
 
-To see the complete list of methods supported by ``mongosh``, refer to:
-:doc:`MongoDB Shell Methods </reference/methods>`.
+.. kicker:: Learn More
 
-Learn More 
-----------
+Other Powerful Features
+-----------------------
 
-- :ref:`Connect to a MongoDB Deployment <mdb-shell-connect>`
+.. card-group::
+   :columns: 3
+   :style: compact
 
-- :ref:`Perform CRUD Operations <mdb-shell-crud>`
+   .. card::
+      :cta: Unlock the Power of Editor Mode
+      :url: https://www.mongodb.com/docs/mongodb-shell/reference/editor-mode/
+      :icon: /images/mongosh-plp/icons/Technical_REALM_CLI10x.png
+      :icon-alt: CLI Icon
 
-- :ref:`Run Aggregation Pipelines <mdb-shell-aggregation>`
+      Use an external or built-in editor to work with multiline
+      functions. Go beyond the line-oriented ``mongosh`` 
+      default console.
 
-- :ref:`Use Editor Mode <mongosh-editor-mode>`.
+   .. card::
+      :cta: Access Session Logs
+      :url: https://www.mongodb.com/docs/mongodb-shell/logs/
+      :icon: /images/mongosh-plp/icons/Technical_MDB_Shell10x.png
+      :icon-alt: MongoDB Shell Icon
 
-- :ref:`Write Scripts <mdb-shell-write-scripts>`
+      Access session logs for any session within the last 30 days. Find 
+      the command syntax you can't quite remember, or look for common
+      commands you can script.
 
-- :ref:`Retrieve Logs <mdb-shell-logs>`
+   .. card::
+      :cta: View Available Methods
+      :url: https://www.mongodb.com/docs/mongodb-shell/reference/methods/
+      :icon: /images/mongosh-plp/icons/General_ACTION_Develop10x.png
+      :icon-alt: Terminal Icon in a circle
 
-- :ref:`View Available Methods in the MongoDB Shell <mdb-shell-methods>`
+      Find out which methods ``mongosh`` supports. Get example
+      syntax and parameter details for supported methods.
 
 .. toctree::
    :titlesonly:
@@ -91,4 +274,3 @@ Learn More
    /reference
    /changelog
    /reference/access-mdb-shell-help.txt
-   

source/images/mongosh-plp/Technical_SOFTWARE_Terminal(1)_Spot.png

@@ -194,6 +194,8 @@ Bulk Operation Methods
      - Returns as a string a JSON document that contains the number of
        operations and batches in the :method:`Bulk()` object.
 
+.. _mongosh-collection-methods:
+
 Collection Methods
 ------------------
 
@@ -639,6 +641,8 @@ Cursor Methods
      - Returns an array that contains all documents returned by the
        cursor.
 
+.. _mongosh-database-methods:
+
 Database Methods
 ----------------
 
@@ -959,6 +963,8 @@ Query Plan Cache Methods
        :manual:`plan cache entries </core/query-plans/>` 
        for a collection.
 
+.. _mongosh-replication-methods:
+
 Replication Methods 
 -------------------
 
@@ -1086,6 +1092,8 @@ Replication Methods
        by hostname for the replica set member that ``mongosh`` is 
        connected to.
 
+.. _mongosh-role-management-methods:
+
 Role Management Methods 
 -----------------------
 
@@ -1188,6 +1196,8 @@ Session Object Methods
      - The options for a session in the shell. To access the
        :method:`SessionOptions()` object, use :method:`Session.getOptions()`. 
 
+.. _mongosh-server-status-methods:
+
 Server Status Methods
 ---------------------
 
@@ -1247,6 +1257,8 @@ Server Status Methods
 
      - Returns the version of the :binary:`~mongod` instance.
 
+.. _mongosh-sharding-methods:
+
 Sharding Methods
 ----------------
 
@@ -1455,6 +1467,8 @@ Transaction Methods
      - Starts a :manual:`multi-document transaction </core/transactions/>`
        associated with the session.
 
+.. _mongosh-user-management-methods:
+
 User Management Methods
 -----------------------
 

source/images/mongosh-plp/Technical_SOFTWARE_Terminal(3)_Spot.png

@@ -1,3 +1,5 @@
+.. _mongosh-require-external-files-and-modules:
+
 =============================================
 Include External Files and Modules in Scripts
 =============================================