(DOCSP-12243): Add Run Commands page and some command behaviors (#49)

* (DOCSP-12243): Add Run Commands page and some command behaviors

WIP

* Updates per feedback

* tweaks

* copy tweak

* formatting fix

Author: jeff-allen-mongo

snooty.toml

@@ -3,7 +3,7 @@ title = "MongoDB Shell"
 
 intersphinx = ["https://docs.mongodb.com/manual/objects.inv"]
 
-toc_landing_pages = ["/crud"]
+toc_landing_pages = ["/run-commands", "/crud"]
 
 [constants]
 

source/changelog.txt

@@ -1,4 +1,4 @@
-.. _mongosh-changelog
+.. _mongosh-changelog:
 
 =====================
 ``mongosh`` Changelog
@@ -58,11 +58,12 @@ the `MongoDB Download Center
 Behavior Updates
 ~~~~~~~~~~~~~~~~
 
-The legacy ``mongo`` shell error handling was not consistent between
-commands. ``mongosh`` now standardizes the user-facing behavior.
-Whenever a shell helper issues a command that results in ``{ ok: 0 }``
-``mongosh`` throws an exception and does not return the raw output from
-the server.
+Whenever a command's output includes ``{ ok: 0 }``, ``mongosh`` throws
+an exception and does not return the raw output from the server.
+
+The legacy ``mongo`` shell error handling is not consistent between
+commands. ``mongosh`` standardizes the user-facing behavior for a
+more consistent experience.
 
 Bug Fixes
 ~~~~~~~~~
@@ -87,7 +88,7 @@ Bug Fixes
   .. note::
 
      ``Ctrl+C`` terminates the process in the shell, but does not
-     terminate the process on the mongodb server.
+     terminate the process on the MongoDB server.
 
 v0.2.2
 ------

source/index.txt

@@ -119,8 +119,7 @@ Learn More
 
       /install
       /connect
-      /crud
-      /run-agg-pipelines
+      /run-commands
       /write-scripts
       /logs
       /reference

source/reference/access-mdb-shell-help.txt

@@ -56,7 +56,9 @@ Show List of Databases
 
      show dbs
 
-  ``show databases`` is an alias for ``show dbs``.
+  .. note::
+
+     ``show databases`` is an alias for ``show dbs``.
 
 Show List of Database Methods
   To see the list of methods you can use on the ``db``

source/run-commands.txt

@@ -0,0 +1,54 @@
+.. _run-commands:
+
+===========================
+Run Commands in ``mongosh``
+===========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. include:: /includes/admonitions/fact-mdb-shell-beta.rst
+
+For documentation of basic MongoDB operations in ``mongosh``, see:
+
+- :doc:`/crud`
+
+- :doc:`/run-agg-pipelines`
+
+- :doc:`/reference/methods`
+
+Terminate a Running Command
+---------------------------
+
+To terminate a running command or query in ``mongosh``,
+press ``Ctrl + C``.
+
+``Ctrl + C`` terminates the process in the shell, but does not
+terminate the process on the MongoDB server. This behavior
+differs from the :method:`db.killOp()` method, which terminates
+commands on the server.
+
+Command Exceptions
+------------------
+
+In scenarios where the output of a command includes ``{ ok: 0 }``,
+``mongosh`` throws an exception and does not return the raw output from
+the server.
+
+.. note::
+
+   In the legacy ``mongo`` shell, when a command's output included ``{
+   ok: 0 }``, the behavior differs between commands. ``mongosh``
+   provides consistent behavior by always throwing an exception in these
+   scenarios.
+
+.. toctree::
+   :titlesonly:
+   
+   /crud
+   /run-agg-pipelines