Merge pull request #73 from ianf-mongodb/DOCSP-34766-b

DOCSP-34766 Improve VSCode Connection Experience

source/connect.txt

@@ -58,88 +58,51 @@ Considerations
 
 .. _vsce-connect-task:
 
-Create a Connection to a Deployment
------------------------------------
+Create a Connection
+-------------------
+
+|vsce| provides two options to connect to your deployment:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40
 
-|vsce| provides two methods to create a connection to a deployment. You 
-can: 
+   * - Connection Method
+     - Description
 
-- Provide a deployment connection string, or 
-- Fill in a deployment information in specific fields.
+   * - :guilabel:`Connect with Connection String`
+     - This method is faster and easier than 
+       using the advanced connection settings. Use this option 
+       if your deployment is hosted on |service| or you already have a 
+       connection string for a deployment available.
 
-Providing a connection string is faster and easier than filling in a 
-deployment's details. Use this option if |service| hosts your 
-deployment or if you have a connection string for a deployment 
-available.
+   * - :guilabel:`Advanced Connection Settings`
+     - This method lets you build a connection string with a form.
+       Use this option if you need to customize the connection 
+       string and want to see available connection options.
 
-Define how your connection is saved with the
-:guilabel:`Default Connection Saving Location`
-:ref:`setting <vsce-settings>`:
+.. note::
 
-.. include:: includes/connection-location-table.rst
+   To specify where |vsce| connections are saved, use 
+   the :guilabel:`Default Connection Saving Location`
+   :ref:`setting <vsce-settings>`.
 
 .. tabs::
 
-   .. tab:: Paste Connection String
-      :tabid: paste-connection-string
+   .. tab:: Connect with Connection String
+      :tabid: connect-with-connection-string
 
       When you provide a connection string, |vsce| supports
       most :manual:`Connection String Options
       </reference/connection-string/#connection-string-options>`
       supported by MongoDB.
 
-      .. include:: /includes/steps/starting-vsce-paste-string.rst
-
-   .. tab:: Fill in Individual Fields
-      :tabid: individual-fields
-
-      .. include:: /includes/steps/starting-vsce-individual-fields.rst
-
-.. _vsce-activate-connection:
-
-Activate a Connection 
----------------------
-
-You can connect |vsce| to only one deployment at a time. To change the
-active connection to a different deployment, or to connect to a 
-deployment from which you were disconnected:
-
-.. include:: /includes/steps/activate-connection.rst
-
-Launch MongoDB Shell
-~~~~~~~~~~~~~~~~~~~~
-
-You can connect the :mongosh:`MongoDB Shell </>` or legacy
-:binary:`mongo <mongo>` shell to your active deployment.
-
-
-Considerations
-``````````````
-
-- The shell that |vsce| uses to connect to your deployment is
-  determined by the :guilabel:`Shell` setting in your
-  :ref:`extension settings <vsce-settings>`. You can choose either
-  the :mongosh:`MongoDB Shell </>` or the legacy :binary:`mongo <mongo>` shell.
+      .. include:: /includes/steps/starting-vsce-connect-with-connection-string.rst
 
-- The path to your selected shell must exist in your system's ``PATH``.
-  If it does not exist in your ``PATH``, the operation errors.
+   .. tab:: Advanced Connection Settings
+      :tabid: Advanced Connection Settings
 
-Procedure
-`````````
-
-To connect the shell to your active deployment:
-
-1. In the |vsce| :guilabel:`Connections` list, right-click your active
-   deployment.
-
-#. Select :guilabel:`Launch MongoDB Shell`.
-
-|vsce| opens the :guilabel:`Terminal` window in VS Code and launches
-the shell connected to your selected deployment.
-
-.. seealso::
-
-   :mongosh:`Perform CRUD Operations in the MongoDB Shell </crud>`
+      .. include:: /includes/steps/starting-vsce-connect-with-advanced-connection-settings.rst
 
 
 .. _vsce-connect-task-atlas-streams:
@@ -207,6 +170,129 @@ For details on how to configure Atlas Stream Processing, see
          :figwidth: 700px
          :alt: Image of a stream processing template
 
+.. _vsce-activate-connection:
+
+Activate a Connection 
+---------------------
+
+You can connect |vsce| to only one deployment at a time. To change the
+active connection to a different deployment, or to connect to a 
+deployment from which you were disconnected:
+
+.. include:: /includes/steps/activate-connection.rst
+
+Launch MongoDB Shell
+~~~~~~~~~~~~~~~~~~~~
+
+You can connect the :mongosh:`MongoDB Shell </>` or legacy
+:binary:`mongo <mongo>` shell to your active deployment.
+
+
+Considerations
+``````````````
+
+- The shell that |vsce| uses to connect to your deployment is
+  determined by the :guilabel:`Shell` setting in your
+  :ref:`extension settings <vsce-settings>`. You can choose either
+  the :mongosh:`MongoDB Shell </>` or the legacy :binary:`mongo <mongo>` shell.
+
+- The path to your selected shell must exist in your system's ``PATH``.
+  If it does not exist in your ``PATH``, the operation errors.
+
+Procedure
+`````````
+
+To connect the shell to your active deployment:
+
+a. In the |vsce| :guilabel:`Connections` list, right-click your active
+   deployment.
+
+#. Select :guilabel:`Launch MongoDB Shell`.
+
+|vsce| opens the :guilabel:`Terminal` window in VS Code and launches
+the shell connected to your selected deployment.
+
+.. seealso::
+
+   :mongosh:`Perform CRUD Operations in the MongoDB Shell </crud>`
+
+.. _vsce-edit-connection-task:
+
+Edit a Connection
+-----------------
+
+.. procedure::
+   :style: normal
+
+
+   .. step:: In |vscode-short|, click the :guilabel:`MongoDB` icon in the :guilabel:`Activity Bar`
+
+        .. figure:: /images/vsce-mongodb-extension-sidemenu.png
+           :figwidth: 600px
+           :alt: Image VSCode side bar menu.
+
+   .. step:: Expand the :guilabel:`Connections` pane 
+
+           Expand the :guilabel:`Connections` pane in the left 
+           navigation if it's collapsed.
+
+           .. figure:: /images/vsce-expand-connections.png
+              :figwidth: 600px
+              :alt: Image showing connections pane
+
+   .. step:: Select a connection
+
+            From the :guilabel:`Connections` menu, right-click the 
+            connection and select :guilabel:`Edit Connection...`
+
+   .. step:: Make changes and save
+
+            Click :icon-fa5:`chevron-right` 
+            :guilabel:`Advanced Connection Options` to display 
+            the advanced connection form.
+
+            .. tip::
+
+               You can also click the :guilabel:`Edit Connection String`
+               toggle in the top-right of the form to edit the connection
+               string URI directly.
+
+            Once you are done editing the connection options click
+            :guilabel:`Save & Connect`.
+
+.. _vsce-copy-connection-string-task:
+
+Copy a Connection
+-----------------
+
+You can copy a connection string from an existing |vscode-short| 
+connection.
+
+.. procedure::
+   :style: normal
+
+   .. step:: In |vscode-short|, click the :guilabel:`MongoDB` icon in the :guilabel:`Activity Bar`
+
+        .. figure:: /images/vsce-mongodb-extension-sidemenu.png
+           :figwidth: 600px
+           :alt: Image VSCode side bar menu.
+
+   .. step:: Expand the :guilabel:`Connections` pane 
+
+           Expand the :guilabel:`Connections` pane in the left 
+           navigation if it's collapsed.
+
+           .. figure:: /images/vsce-expand-connections.png
+              :figwidth: 600px
+              :alt: Image showing connections pane
+
+   .. step:: Select a connection
+
+            From the :guilabel:`Connections` menu, right-click the 
+            connection and select :guilabel:`Copy Connection String`.
+
+            The connection string is copied to your clipboard.
+
 .. _vsce-rename-connection:
 
 Rename a Connection
@@ -223,35 +309,37 @@ Disconnect from a Deployment
 
 |vsce| provides two methods to disconnect from a deployment. You can:
 
-- Disconnect with the Command Palette, or
+- Disconnect with the Command Palette.
 - Disconnect from the :guilabel:`MongoDB` view in the 
   :guilabel:`Activity Bar`.
 
 .. tabs::
 
-   .. tab:: Disconnect with the Command Palette
-      :tabid: command-palette
-
-      .. include:: /includes/steps/disconnect-command-palette.rst
-
-   .. tab:: Disconnect from the MongoDB View
+   .. tab:: MongoDB View
       :tabid: mdb-view
 
       .. include:: /includes/steps/disconnect-mongodb-view.rst
 
+   .. tab:: Command Palette
+      :tabid: command-palette
+
+      .. include:: /includes/steps/disconnect-command-palette.rst
+
 Disconnecting from a MongoDB instance closes the |vsce| connection to 
 the active instance. You must :ref:`reconnect <vsce-connect-task>` to 
 interact with data in your deployment again.
 
+.. _vsce-remove-connection-task:
+
 Remove a Connection
 -------------------
 
 |vsce| provides two methods to remove a connection to a deployment from
 |vscode-short|. You can:
 
-- Remove a connection with the Command Palette, or
 - Remove a connection from the :guilabel:`MongoDB` view in the 
   :guilabel:`Activity Bar`.
+- Remove a connection with the Command Palette.
 
 .. important::
 
@@ -260,16 +348,16 @@ Remove a Connection
 
 .. tabs::
 
-   .. tab:: Remove Connection with the Command Palette
-      :tabid: command-palette
-
-      .. include:: /includes/steps/remove-connection-command-palette.rst
-
-   .. tab:: Remove Connection from the MongoDB View
+   .. tab:: MongoDB View
       :tabid: mdb-view
 
       .. include:: /includes/steps/remove-connection-mdb-view.rst
 
+   .. tab:: Command Palette
+      :tabid: command-palette
+
+      .. include:: /includes/steps/remove-connection-command-palette.rst
+
 .. seealso::
 
    :ref:`playground-connect-to-deployment`

source/includes/steps-activate-connection.yaml

@@ -4,7 +4,7 @@ source:
   file: steps-open-mongodb-view.yaml
   ref: open-mongodb-view
 ---
-title: "Right-click the connection you want to activate, then click :guilabel:`Connect`."
+title: "Right-click the connection you want to activate, then click :guilabel:`Connect`"
 level: 4
 ref: activate-connection
 ...

source/includes/steps-disconnect-command-palette.yaml

@@ -4,12 +4,12 @@ source:
   ref: vsce-command-palette
 ref: vsce-connect-command-palette
 ---
-title: Disconnect.
+title: Disconnect
 level: 4
 ref: vsce-disconnect
 content: |
    
-   #. From the Command Palette, select 
+   a. From the Command Palette, select 
       :guilabel:`MongoDB: Disconnect`. 
 
       .. include:: /includes/admonitions/tip-mongodb-command-palette.rst

source/includes/steps-open-mongodb-view.yaml

@@ -1,5 +1,11 @@
 ---
-title: "In |vscode-short|, click the :guilabel:`MongoDB` view in the :guilabel:`Activity Bar`."
+title: "In |vscode-short|, click the :guilabel:`MongoDB` icon in the :guilabel:`Activity Bar`"
 level: 4
 ref: open-mongodb-view
+content: |
+
+     .. figure:: /images/vsce-mongodb-extension-sidemenu.png
+        :figwidth: 600px
+        :alt: Image VSCode side bar menu.
+
 ...

source/includes/steps-source-command-palette.yaml

@@ -1,13 +1,13 @@
 ---
-title: "In |vscode-short|, open the Command Palette."
+title: "Open the Command Palette"
 level: 4
 ref: vsce-command-palette
 content: |
 
   .. include:: /includes/list-tables/command-palette-options.rst
 ---
 title: "From the Command Palette, choose where you want to save the 
-      connection."
+      connection"
 level: 4
 ref: vsce-connect-save
 content: |