(DOCSP-5127): Connection page refactor (#137)

* (DOCSP-5127): Connection page refactor

* In-progress review updates

* Updates per Gilberto

* Updates per Gilberto's review

Author: jeff-allen-mongo

source/connect.txt

@@ -11,161 +11,35 @@ Connect to MongoDB
    :backlinks: none
    :depth: 1
    :class: singlecol
+  
+This page outlines how to use |compass-short| to connect to your
+MongoDB host.
 
 Connect
 -------
 
 .. include:: /includes/steps/starting-compass.rst
 
-.. _favorite-connections:
-
-Favorite Connections
---------------------
-
-|compass| allows you to save MongoDB connection configurations to
-easily reconnect to the same MongoDB deployment using the same
-specifications. To load a favorite connection into the
-:guilabel:`Connect` form, click the desired connection in the
-:guilabel:`Favorites` list to the left of the form.
-
-Edit a Favorite Connection
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To edit a saved favorite connection:
-
-1. Load the connection into the :guilabel:`Connect` form.
-
-#. Make the desired changes to the connection configuration
-   within the form.
-
-#. Click :guilabel:`Save Favorite` at the bottom of the form.
-
-.. note::
-
-   You can use this process to edit the name of a favorite
-   connection.
-
-Delete a Favorite Connection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To delete a saved favorite connection:
-
-1. Load the connection into the :guilabel:`Connect` form.
-
-#. Click :guilabel:`Delete Favorite` at the bottom of the form.
-
-|compass| removes the connection from the :guilabel:`Favorites` list
-and returns to the :guilabel:`New Connection` view.
-
-.. _required-access:
-
-Required Access
----------------
-
-With authentication/authorization enforced on the connected MongoDB
-instance, the user requires appropriate privileges to access various
-features. The following table lists the privileges required to access
-the features as well as the built-in roles that can provide these
-privileges:
-
-.. note::
-   The built-in roles may provide more access than required. You can
-   also create a :ref:`user-defined-roles` to grant specific privileges.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 25 30 25 20
-
-   * - View
-     - Feature/Action
-     - Privilege(s)
-     - MongoDB Built-In Role
-
-   * - :guilabel:`Home/MongoDB Instance`
-     - :doc:`/performance`
-     - | :authaction:`top`
-       | :authaction:`inprog`
-       | :authaction:`serverStatus`
-     - :authrole:`clusterMonitor`
-
-   * - :guilabel:`Database`
-     - :ref:`create-database`
-     - :authaction:`createCollection`
-     - :authrole:`readWrite`
-
-   * - :guilabel:`Database`
-     - :ref:`drop-database`
-     - :authaction:`dropDatabase`
-     - :authrole:`dbAdmin`
-
-   * - :guilabel:`Collection`
-     - :ref:`create-collection`
-     - :authaction:`createCollection`
-     - :authrole:`readWrite`
-
-   * - :guilabel:`Collection`
-     - :ref:`drop-collection`
-     - :authaction:`dropCollection`
-     - :authrole:`readWrite`
-
-   * - :guilabel:`Schema`
-     - :doc:`Query/View <schema>`
-     - :authaction:`find`
-     - :authrole:`read`
-
-   * - :guilabel:`Documents`
-     - :doc:`Query/View </documents>`
-     - :authaction:`find`
-     - :authrole:`read`
-
-   * - :guilabel:`Documents`
-     - :doc:`Clone, insert, update, delete </documents>`
-     - | :authaction:`find`
-       | :authaction:`insert`
-       | :authaction:`update`
-       | :authaction:`remove`
-     - :authrole:`readWrite`
-
-   * - :guilabel:`Indexes`
-     - :doc:`View </indexes>`
-     - :authaction:`listIndexes`
-     - :authrole:`read`
-
-   * - :guilabel:`Indexes`
-     - :doc:`Create, drop </indexes>`
-     - | :authaction:`createIndex`
-       | :authaction:`dropIndex`
-     - :authrole:`readWrite`
-
-   * - :guilabel:`Explain Plan`
-     - :doc:`Query/View </query-plan>`
-     - :authaction:`find`
-     - :authrole:`read`
-
-   * - :guilabel:`Validation`
-     - :doc:`View rules </validation>`
-     - :authaction:`listCollections`
-     - :authrole:`read`
-
-   * - :guilabel:`Validation`
-     - :ref:`Update rules <update-validation>`
-     - :authaction:`collMod`
-     - :authrole:`dbAdmin`
-
 .. _disconnect:
 
 Disconnect
 ----------
 
-To disconnect from a MongoDB instance in Compass:
-
-- Click :guilabel:`Connect` in the menu bar, then
-- Select :guilabel:`Disconnect` from the dropdown menu
-
-.. figure:: images/compass/disconnect.png
+.. include:: /includes/steps/disconnect-compass.rst
 
 Disconnecting from a MongoDB instance closes the Compass connection to
 the active instance and returns the Compass view to the initial
 connection dialog.
 
+.. figure:: images/compass/disconnect.png
+
 .. |home| unicode:: U+2302
+
+.. class:: hidden
+
+   .. toctree::
+      :titlesonly:
+   
+      /connect/required-access
+      /connect/favorite-connections
+      

source/connect/favorite-connections.txt

@@ -0,0 +1,36 @@
+.. _favorite-connections:
+
+====================
+Favorite Connections
+====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+|compass| allows you to save MongoDB connection configurations to
+easily reconnect to the same MongoDB deployment using the same
+specifications.
+
+Save a Favorite Connection
+--------------------------
+
+.. include:: /includes/steps/favorite-connection-save.rst
+
+.. figure:: /images/compass/favorite-connection.png
+   :figwidth: 500px
+   :alt: Image showing Favorite Connection in Compass
+
+Edit a Favorite Connection
+--------------------------
+
+.. include:: /includes/steps/favorite-connection-edit.rst
+
+Delete a Favorite Connection
+----------------------------
+
+.. include:: /includes/steps/favorite-connection-delete.rst

source/connect/required-access.txt

@@ -0,0 +1,100 @@
+.. _required-access:
+
+===============
+Required Access
+===============
+
+.. default-domain:: mongodb
+
+|compass| users require specific privileges to access various
+|compass-short| features if authentication/authorization is enforced on
+the connected MongoDB instance.
+
+The following table lists the privileges required to access the
+features as well as the built-in roles that can provide these
+privileges:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 30 25 20
+
+   * - Compass View
+     - Capability
+     - Privilege(s)
+     - MongoDB Built-In Role
+
+   * - :guilabel:`Home/MongoDB Instance`
+     - :doc:`View performance </performance>`
+     - | :authaction:`top`
+       | :authaction:`inprog`
+       | :authaction:`serverStatus`
+     - :authrole:`clusterMonitor`
+
+   * - :guilabel:`Database`
+     - :ref:`create-database`
+     - :authaction:`createCollection`
+     - :authrole:`readWrite`
+
+   * - :guilabel:`Database`
+     - :ref:`drop-database`
+     - :authaction:`dropDatabase`
+     - :authrole:`dbAdmin`
+
+   * - :guilabel:`Collection`
+     - :ref:`create-collection`
+     - :authaction:`createCollection`
+     - :authrole:`readWrite`
+
+   * - :guilabel:`Collection`
+     - :ref:`drop-collection`
+     - :authaction:`dropCollection`
+     - :authrole:`readWrite`
+
+   * - :guilabel:`Schema`
+     - :doc:`Query/View a Schema </schema>`
+     - :authaction:`find`
+     - :authrole:`read`
+
+   * - :guilabel:`Documents`
+     - :doc:`Query/View a Document </documents>` 
+     - :authaction:`find`
+     - :authrole:`read`
+
+   * - :guilabel:`Documents`
+     - :doc:`Clone, insert, update, delete a document </documents>` 
+     - | :authaction:`find`
+       | :authaction:`insert`
+       | :authaction:`update`
+       | :authaction:`remove`
+     - :authrole:`readWrite`
+
+   * - :guilabel:`Indexes`
+     - :doc:`View an index </indexes>`
+     - :authaction:`listIndexes`
+     - :authrole:`read`
+
+   * - :guilabel:`Indexes`
+     - :doc:`Create, drop an index </indexes>`
+     - | :authaction:`createIndex`
+       | :authaction:`dropIndex`
+     - :authrole:`readWrite`
+
+   * - :guilabel:`Explain Plan`
+     - :doc:`Query/View a query plan </query-plan>`
+     - :authaction:`find`
+     - :authrole:`read`
+
+   * - :guilabel:`Validation`
+     - :doc:`View rules </validation>`
+     - :authaction:`listCollections`
+     - :authrole:`read`
+
+   * - :guilabel:`Validation`
+     - :ref:`Update rules <update-validation>`
+     - :authaction:`collMod`
+     - :authrole:`dbAdmin`
+
+.. note::
+
+   The built-in roles may provide more access than required. You can
+   also create a :ref:`user-defined-roles` to grant specific privileges.

source/images/compass/connect-to-host.png

@@ -37,20 +37,14 @@ method from the tabs below for specific instructions:
          authentication mechanism, see :manual:`SCRAM
          </manual/core/security-scram/>`.
 
-     - id: x509
-       name: X.509
-       content: |
-         *Not Available in Compass Community Edition*
-
-         Select :guilabel:`X.509` if the ``mongod`` instance uses
-         :manual:`X.509 </core/security-x.509/>` as its authentication
-         mechanism. If selected, you must provide the
-         :guilabel:`Username` to authenticate the user.
-
      - id: kerberos
        name: Kerberos
        content: |
-         *Not Available in Compass Community Edition*
+
+         .. important::
+
+            :guilabel:`Kerberos` Authentication is not available in
+            Compass Community Edition.
 
          Select :guilabel:`Kerberos` if the ``mongod`` instance uses
          :manual:`Kerberos </core/kerberos/>` as its authentication
@@ -73,13 +67,29 @@ method from the tabs below for specific instructions:
      - id: ldap
        name: LDAP
        content: |
-         *Not Available in Compass Community Edition*
+         .. important::
+
+            :guilabel:`LDAP` Authentication is not available in
+            Compass Community Edition.
 
          Select :guilabel:`LDAP` if the ``mongod`` instance uses
          :manual:`LDAP </core/security-ldap-external/>` as its
          authentication mechanism. If selected, you must provide the
          :guilabel:`Username` and :guilabel:`Password` to authenticate
          the user.
 
+     - id: x509
+       name: X.509
+       content: |
+         .. important::
+
+            :guilabel:`x.509` Authentication is not available in
+            Compass Community Edition.
+
+         Select :guilabel:`X.509` if the ``mongod`` instance uses
+         :manual:`X.509 </core/security-x.509/>` as its authentication
+         mechanism. If selected, you must provide the
+         :guilabel:`Username` to authenticate the user.
+
 For MongoDB permissions required to access |compass-short|,
 see :ref:`required-access`.

source/images/compass/disconnect.png

@@ -0,0 +1,5 @@
+Hostname of the machine where the ``mongod`` instance is running. If
+you are running your ``mongod`` locally, this value is ``localhost``.
+
+If you are not sure of your hostname, contact your Database
+Administrator for information.

source/images/compass/favorite-connection-select.png

@@ -0,0 +1,12 @@
+Port on which ``mongod`` is running. Not required if you
+are using an :guilabel:`SRV Record` to connect to
+your MongoDB instance.
+
+By default, a standalone ``mongod`` operates on port
+``27017``. If you are connecting to a replica set, your port
+may also be ``27018`` or ``27019``. For more information on
+the default ports MongoDB operates on, see
+:manual:`Default MongoDB Port </reference/default-mongodb-port/>`.
+
+If you are not sure of the port where your ``mongod`` operates,
+contact your Database Administrator for information.