(DOCSP-23224): TOC refactor (#216)

jeff-allen-mongo · web-flow · commit e6b9c2672f7a · 2022-06-16T13:51:58.000-04:00
* (DOCSP-23224): TOC refactor * fix page title * remove toc on usage page * change title * add configuration landing page * tweaks * improvements to write scripts page * wording * more adjustments * fix formatting * more tweaks * adjust heading * adjustments * fix line number example copy * remove extra blank lines * add toc to script limitations page * clarification * formatting * fix mongorc.js formatting * add heading * formatting * fix page titles and alphabetize * address feedback * remove gerunds * remove editor mode from landing page
diff --git a/snooty.toml b/snooty.toml
@@ -8,6 +8,7 @@ toc_landing_pages = ["/run-commands",
                      "/field-level-encryption",
                      "/write-scripts",
                      "/snippets",
+                     "/configure-mongosh",
                      "/reference/configure-shell-settings"
                     ]
 
diff --git a/source/changelog.txt b/source/changelog.txt
@@ -1,8 +1,8 @@
 .. _mongosh-changelog:
 
-=====================
-``mongosh`` Changelog
-=====================
+=============
+Release Notes
+=============
 
 .. default-domain:: mongodb
 
diff --git a/source/configure-mongosh.txt b/source/configure-mongosh.txt
@@ -0,0 +1,30 @@
+.. _mongosh-configure:
+
+=====================
+Configure ``mongosh``
+=====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Learn how to configure ``mongosh`` behaviors and user experience:
+
+- :ref:`mongosh-editor-mode`
+- :ref:`mongosh-shell-settings`
+- :ref:`customize-the-mongosh-prompt`
+- :ref:`telemetry`
+- :ref:`free-monitoring-mongosh`
+
+.. toctree::
+   :titlesonly:
+ 
+   /reference/editor-mode
+   /reference/configure-shell-settings
+   /reference/customize-prompt
+   /telemetry
+   /free-monitoring
diff --git a/source/free-monitoring.txt b/source/free-monitoring.txt
@@ -1,8 +1,8 @@
 .. _free-monitoring-mongosh:
 
-===============
-Free Monitoring
-===============
+=========================
+Configure Free Monitoring
+=========================
 
 .. default-domain:: mongodb
 
diff --git a/source/includes/examples/ex-display-line-numbers.rst b/source/includes/examples/ex-display-line-numbers.rst
@@ -1,5 +1,5 @@
-This code will dynamically update the :binary:`~bin.mongosh` prompt
-to display line numbers:
+To display line numbers in the :binary:`~bin.mongosh` prompt, run the
+following code inside ``mongosh``:
 
 .. code-block:: javascript
 
@@ -15,4 +15,3 @@ The prompt will look like this:
    1> show collections
    2> use test
    3>
-
diff --git a/source/includes/fact-mongoshrc-loading.rst b/source/includes/fact-mongoshrc-loading.rst
@@ -1,24 +1,20 @@
-On startup, :binary:`mongosh` checks the user's ``HOME`` directory for
-a JavaScript file named :ref:`.mongoshrc.js <mongoshrc-js>`. If this
-file is found, :binary:`mongosh` reads the content of
-:ref:`.mongoshrc.js <mongoshrc-js>` before displaying the prompt for
-the first time.
+On startup, :binary:`mongosh` checks your ``HOME`` directory for a
+JavaScript file named .mongoshrc.js. If this file is found,
+:binary:`mongosh` reads the content of .mongoshrc.js before
+displaying the prompt for the first time.
 
 If you use :binary:`mongosh` to evaluate a JavaScript file or
-expression, either by using the :option:`--eval <mongosh --eval>`
-option on the command line or by specifying a :ref:`.js file
-<mdb-shell-execute-file>`, :binary:`mongosh` reads :ref:`.mongoshrc.js
-<mongoshrc-js>` *after* the JavaScript has finished processing. You can
-prevent :ref:`.mongoshrc.js <mongoshrc-js>` from being loaded by using
-the :option:`--norc <mongosh --norc>` option.
+expression, either by using the :option:`--eval <mongosh --eval>` option
+on the command line or by specifying a :ref:`.js file
+<mdb-shell-execute-file>`, :binary:`mongosh` reads .mongoshrc.js
+*after* the JavaScript has finished processing. You can prevent
+.mongoshrc.js from being loaded by using the :option:`--norc
+<mongosh --norc>` option.
 
 .. note::
 
-   The legacy :binary:`~bin.mongo` shell used a configuation file
-   called ``.mongorc.js``. If :binary:`mongosh` detects this file on
-   startup, and :ref:`.mongoshrc.js <mongoshrc-js>` is not present,
-   :binary:`mongosh` will suggest renaming ``.mongorc.js`` to
-   :ref:`.mongoshrc.js <mongoshrc-js>`. 
-
-   The legacy ``.mongorc.js`` file is not loaded.
-
+   The legacy :binary:`~bin.mongo` shell used a configuration file
+   called .mongorc.js. If :binary:`mongosh` detects this file on
+   startup, and .mongoshrc.js is not present, :binary:`mongosh` does not
+   load the legacy .mongorc.js file, and suggests renaming .mongorc.js
+   to .mongoshrc.js.
diff --git a/source/index.txt b/source/index.txt
@@ -27,8 +27,8 @@ MongoDB download center.
 Download and Install ``mongosh``
 --------------------------------
 
-To learn how to download and install the :binary:`~bin.mongosh` binary,
-see :ref:`mdb-shell-install`.
+To learn how to download and install the ``mongosh`` binary, see
+:ref:`mdb-shell-install`.
 
 Connect to a MongoDB Deployment
 -------------------------------
@@ -37,20 +37,6 @@ 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`.
 
-.. _mdb-shell-multi-line:
-
-``mongosh`` Editor Mode
------------------------
-
-The :binary:`~bin.mongosh` console is line oriented. However, you can
-also use an editor to work with multiline functions. There are two
-options:
-
-- An external editor, accessed with the ``edit`` command
-- A built-in editor, accessed with the ``.editor`` command
-
-For further details see :ref:`mongosh-editor-mode`.
-
 The |mdb-shell| versus the Legacy ``mongo`` Shell
 -------------------------------------------------
 
@@ -95,14 +81,12 @@ Learn More
 
    /install
    /connect
-   /free-monitoring
-   /field-level-encryption
-   /logs
+   /configure-mongosh
    /run-commands
-   /snippets
+   /crud
+   /run-agg-pipelines
+   /field-level-encryption
    /write-scripts
+   /snippets
    /reference
    /reference/access-mdb-shell-help.txt
-   /reference/compatibility
-   /changelog
-
diff --git a/source/mongoshrc.txt b/source/mongoshrc.txt
@@ -18,35 +18,9 @@
 
 .. include:: /includes/fact-mongoshrc-loading.rst
 
-Examples
---------
-
-The following examples create custom prompts. To display:
-
-- :ref:`line numbers <ex-display-line-numbers>`
-- :ref:`database and hostname <ex-display-dbname-and-hostname>`
-- :ref:`system uptime and document count <ex-display-system-up-time>`
-
-add the example code to :ref:`.mongoshrc.js <mongoshrc-js>`.
-
-.. _ex-display-line-numbers:
-
-Display Line Numbers
-~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /includes/examples/ex-display-line-numbers.rst
-
-.. _ex-display-dbname-and-hostname:
-
-Display Database and Hostname
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /includes/examples/ex-display-dbname-and-hostname.rst
-
-.. _ex-display-system-up-time:
-
-Display System Up Time and Document Count
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /includes/examples/ex-display-system-uptime.rst
+Example Usage
+-------------
 
+You can use the .mongoshrc file to customize ``mongosh`` startup
+behavior and add scripted functionality. For examples, see
+:ref:`mongosh-write-scripts-config-file`.
diff --git a/source/reference.txt b/source/reference.txt
@@ -9,9 +9,10 @@ Reference
    .. toctree::
       :titlesonly:
 
-      /reference/configure-shell-settings
-      /reference/editor-mode
+      /reference/compatibility
       /reference/data-types
       /reference/methods
+      /mongoshrc
       /reference/options
-
+      /changelog
+      /logs
diff --git a/source/reference/access-mdb-shell-help.txt b/source/reference/access-mdb-shell-help.txt
@@ -1,9 +1,9 @@
 .. _mdb-shell-help:
 .. _mongosh-help:
 
-==========================
-Access Help in ``mongosh``
-==========================
+================
+``mongosh`` Help
+================
 
 .. default-domain:: mongodb
 
@@ -436,5 +436,3 @@ certain database commands and obtain information on your deployment:
 
    * - ``show users``
      - Display a list of users for current database.
-
-
diff --git a/source/reference/configure-shell-settings-api.txt b/source/reference/configure-shell-settings-api.txt
@@ -1,8 +1,8 @@
 .. _configure-settings-api:
 
-==============================================
-Configure :binary:`~bin.mongosh` Using the API
-==============================================
+================================
+Configure Settings Using the API
+================================
 
 .. default-domain:: mongodb
 
diff --git a/source/reference/configure-shell-settings-global.txt b/source/reference/configure-shell-settings-global.txt
@@ -1,8 +1,8 @@
 .. _configure-settings-global:
 
-===========================================================
-Configure :binary:`~bin.mongosh` Using a Configuration File
-===========================================================
+=============================================
+Configure Settings Using a Configuration File
+=============================================
 
 .. default-domain:: mongodb
 
diff --git a/source/reference/configure-shell-settings.txt b/source/reference/configure-shell-settings.txt
@@ -1,8 +1,8 @@
 .. _mongosh-shell-settings:
 
-================================
-Configure :binary:`~bin.mongosh`
-================================
+==================
+Configure Settings
+==================
 
 .. default-domain:: mongodb
 
@@ -35,4 +35,3 @@ To configure ``mongosh`` settings, you can either use:
 
    /reference/configure-shell-settings-api
    /reference/configure-shell-settings-global
-   /reference/customize-prompt
diff --git a/source/reference/data-types.txt b/source/reference/data-types.txt
@@ -1,6 +1,6 @@
-======================
-``mongosh`` Data Types
-======================
+==========
+Data Types
+==========
 
 .. default-domain:: mongodb
 
@@ -636,4 +636,3 @@ the output of :method:`db.collection.find()` is a ``Cursor``.
 
    var findResults = db.housing.find({"multiUnit": true} )
    findResults.constructor.name     // Returns the type
-
diff --git a/source/reference/editor-mode.txt b/source/reference/editor-mode.txt
@@ -1,8 +1,9 @@
 .. _mongosh-editor-mode:
+.. _mdb-shell-multi-line:
 
-===========
-Editor Mode
-===========
+==========================
+Use an Editor for Commands
+==========================
 
 .. default-domain:: mongodb
 
@@ -328,4 +329,3 @@ To leave the editor,
 Objects which are declared using ``.editor``, like ``albums`` in this
 example, are added to the global scope. They are available after
 ``.editor`` closes.
-
diff --git a/source/reference/methods.txt b/source/reference/methods.txt
@@ -1,8 +1,8 @@
 .. _mdb-shell-methods:
 
-===================
-``mongosh`` Methods
-===================
+=======
+Methods
+=======
 
 .. default-domain:: mongodb
 
diff --git a/source/reference/options.txt b/source/reference/options.txt
@@ -1,6 +1,6 @@
-===================
-``mongosh`` Options
-===================
+=======
+Options
+=======
 
 .. default-domain:: mongodb
 
diff --git a/source/run-commands.txt b/source/run-commands.txt
diff --git a/source/snippets.txt b/source/snippets.txt
diff --git a/source/snippets/packages.txt b/source/snippets/packages.txt
diff --git a/source/snippets/reference.txt b/source/snippets/reference.txt
diff --git a/source/snippets/working-with-snippets.txt b/source/snippets/working-with-snippets.txt
diff --git a/source/telemetry.txt b/source/telemetry.txt
diff --git a/source/write-scripts.txt b/source/write-scripts.txt
diff --git a/source/write-scripts/limitations.txt b/source/write-scripts/limitations.txt

Original file line number	Diff line number	Diff line change
`@@ -8,6 +8,7 @@ toc_landing_pages = ["/run-commands",`
`8`	`8`	`"/field-level-encryption",`
`9`	`9`	`"/write-scripts",`
`10`	`10`	`"/snippets",`
	`11`	`+ "/configure-mongosh",`
`11`	`12`	`"/reference/configure-shell-settings"`
`12`	`13`	`]`
`13`	`14`