(DOCSP-10094): Remove/change '--profile' in examples (#107)

* (DOCSP-10094): Remove/change '--profile' in examples

* Tech & copy review

* Create a default profile source constant

* More updates

* Cleanup, replace more default profile source constants

* Add links to project ID in quick start

* Copy review 2

Author: melissamahoney-mongodb

conf.py

@@ -57,10 +57,12 @@
 pygments_style = 'sphinx'
 
 source_constants = {
+    'default-profile': ':ref:`default profile <mcli-profiles>`',
     'version': version,
     'mcli': 'MongoDB CLI',
     'mcli-long': 'MongoDB Command Line Interface (``mongocli``)',
     'mcli-version': '0.5.0',
+    'mdbVersion': '4.2',
     'mdbagent': 'MongoDB Agent',
     'aagent': 'Automation Agent',
     'magent': 'Monitoring Agent',

snooty.toml

@@ -1,8 +1,10 @@
 name = "mongocli"
 
 [constants]
+default-profile = ":ref:`default profile <mcli-profiles>`"
 mcli = "MongoDB CLI"
 mcli-long = "MongoDB Command Line Interface (``mongocli``)"
 mcli-version = "0.5.0"
 mdbagent = "MongoDB Agent"
+mdbVersion = "4.2"
 aagent = "Automation Agent"

source/configure/configuration-file.txt

@@ -12,51 +12,93 @@
    :depth: 1
    :class: singlecol
 
-The {+mcli+} configuration file stores related settings and
-|api| keys in groups called *profiles*. You can define multiple profiles
-so that you can use the {+mcli+} to access different MongoDB services or
-projects from the same terminal. You can update the settings stored in
-your configuration file by editing the file with a text editor or
-by using the ``mongocli config set`` command. 
+The {+mcli+} configuration file stores your profiles. You can update the
+settings stored in your configuration file by editing the file with a
+text editor or by using the :ref:`mcli-config-set-command` command.
 
 .. include:: /includes/admonitions/secure-config-file.rst
 
 Configuration File Location
 ---------------------------
 
 The first time you run the :ref:`mcli-config-command` command, the
-{+mcli+} creates a configuration file called ``mongocli.toml`` and grants
-you read and write access to the file. The {+mcli+} saves the
-configuration file to the folder where your system stores application
-configuration files, which is defined by the ``$XDG_CONFIG_HOME``
-environment variable. By default, this location is the ``/.config``
-folder of your home directory. If this folder doesn't exist, the
-{+mcli+} creates the folder and grants you read, write, and execute
-permissions.
+{+mcli+} creates a configuration file called ``mongocli.toml``. The
+{+mcli+} grants the user who ran the command read and write access to
+the file. The {+mcli+} saves the configuration file to the folder where
+the system stores application configuration files, which is defined by
+the ``$XDG_CONFIG_HOME`` environment variable. By default, this location
+is the ``/.config`` folder of the user's home directory. If this folder
+doesn't exist, the {+mcli+} creates the folder and grants the user read,
+write, and execute permissions.
+
+.. _mcli-profiles:
+
+Profiles
+--------
+
+The {+mcli+} configuration file stores related settings and
+|api| keys in groups called *profiles*. You can create or define
+multiple profiles so that you can use the {+mcli+} to access different
+MongoDB services or projects from the same terminal.
+
+To run {+mcli+} with a specific profile, append the ``--profile
+<profileName>`` option to the command. If you omit the ``--profile``
+parameter, {+mcli+} looks for a profile named ``default`` in the
+configuration file.
 
 Example
 -------
 
 The following example configuration file contains two profiles,
-``default`` and ``myOpsManager``. The ``default`` profile contains |api|
-keys, an organization ID, and a project ID for an |service| deployment.
-The ``myOpsMgr`` profile contains |api| keys, the base |url|, an
-organization ID, and a project ID for an |onprem| deployment.
+``default`` and ``myOpsManager``. 
 
-.. code-block:: sh
+The ``default`` profile connects to a |service| deployment and contains
+the following settings:
+
+- An organization ID
+- |api| keys
+- A project ID
+
+The ``myOpsManager`` profile connects to an |onprem| deployment and
+contains contains the following settings:
+
+- The |onprem| base |url|
+- An organization ID
+- |api| keys
+- A project ID
+
+.. code-block:: text
+   :copyable: false
+
+   # ~/.config/mongocli.toml
 
    [default]
-   service=cloud
-   public_api_key=ABCDEFG
-   private_api_key=e750d2bf-1234-4cde-5678-ca4dcbcac9a4
-   organization_id=qwer5678uiop23jb45lk78mn
-   project_id=5e2f04ecf10fcd33c7d4077e
-
-   [myOpsMgr]
-   service=om
-   public_api_key=HIJKLMN
-   private_api_key=e750d2bf-9101-4cde-1121-ca4dcbcac9a5
-   ops_manager_url=http://localhost:9080
-   organization_id=jklsa23123dsdf3jj456hs2
-   project_id=kk12jdn43jd123dkdkf97jg
+     organization_id = "qwer5678uiop23jb45lk78mn"
+     public_api_key = "ABCDEFG"
+     project_id= "5e2f04ecf10fcd33c7d4077e"
+     private_api_key = "e750d2bf-1234-4cde-5678-ca4dcbcac9a4"
+     service = "cloud"
+
+   [myOpsManager]
+     ops_manager_url = "http://localhost:9080/"
+     organization_id = "jklsa23123dsdf3jj456hs2"
+     public_api_key = "HIJKLMN"
+     project_id = "kk12jdn43jd123dkdkf97jg"
+     private_api_key = "e750d2bf-9101-4cde-1121-ca4dcbcac9a5"
+     service = "ops-manager"
+
+To use {+mcli+} with the ``default`` profile, omit the ``--profile``
+option from the command:
+
+.. code-block:: sh
+   :copyable: false
+
+   mongocli <command>
+
+To use {+mcli+} with the ``myOpsManager`` profile, append the
+``--profile myOpsManager`` option to the command:
+
+.. code-block:: sh
+   :copyable: false
 
+   mongocli <command> --profile myOpsManager

source/includes/admonitions/note-atlas-api-free-tier-limits.rst

@@ -0,0 +1,5 @@
+.. note::
+
+   This feature is not available for ``M0`` (Free Tier) clusters. For
+   more information, see :atlas:`Atlas M0 (Free Tier) Limitations
+   </reference/free-shared-limitations/index.html>`.

source/includes/alert-describe-options.rst

@@ -16,7 +16,7 @@
      - string
      - Name of the profile where the public and private 
        keys for the project are saved. If omitted, uses the 
-       ``default`` profile. To learn more about creating a 
+       {+default-profile+}. To learn more about creating a 
        profile, see :ref:`mcli-configure`.
      - no
 
@@ -25,4 +25,4 @@
      - Unique identifier of the project that contains the 
        alert to describe. If omitted, uses the project ID in 
        the profile or :ref:`environment variable <mcli-env-var>`.
-     - yes
+     - yes

source/includes/alert-list-options.rst

@@ -22,7 +22,7 @@
      - string
      - Name of the profile where the public and private 
        keys for the project are saved. If omitted, uses the 
-       ``default`` profile. To learn more about creating a 
+       {+default-profile+}. To learn more about creating a 
        profile, see :ref:`mcli-configure`.
      - no
 
@@ -53,4 +53,4 @@
           * - ``CLOSED``
             - Alert is closed.
 
-     - no
+     - no

source/includes/alerts-ack-options.rst

@@ -37,10 +37,10 @@
 
    * - ``--profile``, ``-P``
      - string
-     - Name of the profile where the project ID and the |svc-api-key|\s
-       for the project are saved. If omitted, uses the ``default``
-       profile.
-
+     - Name of the profile where the project ID and the |svc-api-key|\s 
+       for the project are saved. If omitted, uses the
+       {+default-profile+}.
+       
        .. seealso::
 
           To learn more about creating a profile, see

source/includes/backup-checkpoints-options.rst

@@ -15,7 +15,7 @@
    * - ``--profile``, ``-P``
      - string
      - Name of the profile where the project ID and the |svc-api-key|\s 
-       for the project are saved. If omitted, uses the ``default`` profile. 
+       for the project are saved. If omitted, uses the {+default-profile+}. 
        To learn more about creating a profile, see :ref:`mcli-configure`.
      - no
 

source/includes/basic-options.rst

@@ -16,7 +16,7 @@
      - string
      - Name of the profile where the public and private 
        keys for the project are saved. If omitted, uses the 
-       ``default`` profile. To learn more about creating a 
+       {+default-profile+}. To learn more about creating a 
        profile, see :ref:`mcli-configure`.
      - no
 

source/includes/list-table-events-list-options.rst

@@ -10,7 +10,7 @@
    * - ``--profile``, ``-P``
      - string
      - Name of the profile where the project ID and the |svc-api-key|\s 
-       for the project are saved. If omitted, uses the ``default`` profile. 
+       for the project are saved. If omitted, uses the {+default-profile+}. 
        To learn more about creating a profile, see :ref:`mcli-configure`.
      - no
 

source/includes/measurements-disks-describe-options.rst

@@ -107,7 +107,7 @@
    * - ``--profile``, ``-P``
      - string
      - Name of the profile where the project ID and the |svc-api-key|\s 
-       for the project are saved. If omitted, uses the ``default`` profile. 
+       for the project are saved. If omitted, uses the {+default-profile+}. 
        To learn more about creating a profile, see :ref:`mcli-configure`.
      - no
 

source/includes/mms-backup-restore-start-options.rst

@@ -83,7 +83,7 @@
    * - ``--profile``, ``-P``
      - string
      - Name of the profile where the project ID and the |svc-api-key|\s 
-       for the project are saved. If omitted, uses the ``default`` profile. 
+       for the project are saved. If omitted, uses the {+default-profile+}. 
        To learn more about creating a profile, see :ref:`mcli-configure`.
      - no
 

source/includes/quick-start-intro.rst

@@ -0,0 +1,6 @@
+You can configure {+mcli+} access to your MongoDB service using
+the :ref:`mcli-config-command` and :ref:`mcli-config-set-command`
+commands. 
+
+The following procedure creates the {+default-profile+} in the
+:ref:`configuration file <mcli-config-file>`. You can use this profile with all the other commands in this tutorial.

source/includes/quick-start-summary.rst

@@ -0,0 +1,3 @@
+Congratulations! You have successfully created a cluster to host your
+data. You can view your cluster by logging in to the UI.
+

source/includes/steps-configure-mcli-atlas.yaml

@@ -3,13 +3,15 @@ source:
   file: steps-configure-mcli.yaml
   ref: create-profile
 replacement:
-  serviceName: "cloud"
+  serviceOption: ""
 ---
 stepnum: 2
 source:
   file: steps-configure-mcli.yaml
   ref: enter-api-key
 replacement:
+  apiKeys: ":atlas:`Programmatic API Key </configure-api-access>`"
+  projectId: ":atlas:`Project ID </tutorial/manage-project-settings/>`"
   service: "|service|"
 ---
 stepnum: 3

source/includes/steps-configure-mcli-cm.yaml

@@ -3,13 +3,15 @@ source:
   file: steps-configure-mcli.yaml
   ref: create-profile
 replacement:
-  serviceName: "cloud-manager"
+  serviceOption: "--service cloud-manager"
 ---
 stepnum: 2
 source:
   file: steps-configure-mcli.yaml
   ref: enter-api-key
 replacement:
+  apiKeys: ":cloudmgr:`Cloud Manager API Access </tutorial/configure-public-api-access>`"
+  projectId: ":cloudmgr:`Project ID </tutorial/manage-project-settings/>`"
   service: "|cloud|"
 ---
 stepnum: 3

source/includes/steps-configure-mcli-om.yaml

@@ -3,7 +3,7 @@ source:
   file: steps-configure-mcli.yaml
   ref: create-profile
 replacement:
-  serviceName: "ops-manager"
+  serviceOption: "--service ops-manager"
 ---
 stepnum: 2
 source:
@@ -15,6 +15,8 @@ source:
   file: steps-configure-mcli.yaml
   ref: enter-api-key
 replacement:
+  apiKeys: ":opsmgr:`Ops Manager API Acess </tutorial/configure-public-api-access>`"
+  projectId: ":opsmgr:`Project ID </tutorial/manage-project-settings/>`"
   service: "|onprem|"
 ---
 stepnum: 4