Updates to service docstring

qiskit_ibm_runtime/qiskit_runtime_service.py

@@ -77,45 +77,86 @@ def __init__(
     ) -> None:
         """QiskitRuntimeService constructor.
 
-        An account is selected in the following order:
-            - If a ``filename`` is specified, account details will be loaded from ``filename``,
-                else they will be loaded from the default configuration file.
-            - If ``name`` is specified, the corresponding account details will be loaded from
-                the configuration file, including ``channel``, ``token``, ``instance``, ``region``,
-                ``plans_preference`, and the advanced configuration parameters: ``url``,
-                ``url_resolver``, ``private_endpoint``,  ``verify``, and  ``proxies``.
-            - If ``channel`` is specified, the default account details for that channel will be
-                loaded from the configuration file, else, the account details will be loaded
-                from the ``default_channel`` defined in the configuration file.
-            - Any loaded details will be overwritten by the corresponding parameter in the
-                service constructor.
+        Recommended uses:
+
+        * Direct instantiation:
+
+            .. code-block:: python
+
+                from qiskit_ibm_runtime import QiskitRuntimeService
+
+                service = QiskitRuntimeService(
+                    channel="ibm_quantum_platform",
+                    token="API_KEY",
+                    instance="CRN"
+                    )
+
+        * Saving default acccount:
+
+            .. code-block:: python
+
+                from qiskit_ibm_runtime import QiskitRuntimeService
+
+                QiskitRuntimeService.save_account(
+                    token="API_KEY",
+                    instance="CRN",
+                    set_as_default = True
+                    )
+
+                service = QiskitRuntimeService()
 
         The minimum required information for service authentication to a non-local channel is the
         ``token``. The ``local`` channel doesn't require authentication.
-        For the ``"ibm_cloud"`` and ``"ibm_quantum_platform"`` channels it is recommended
-        to provide the relevant ``instance`` to minimize API calls. If an ``instance`` is not defined,
-        the service will fetch all instances accessible within the account, filtered by
-        ``region``, ``plans_preference``, and ``tags``.
+        For non-local channels, it is recommended to always provide the relevant ``instance``
+        to minimize API calls. If an ``instance`` is not defined, the service will fetch all
+        instances accessible within the
+        account, filtered by ``region``, ``plans_preference``, and ``tags``.
+
+        The service will attempt to load an account from file if (a) no explicit ``token``
+        was provided during instantiation  or (b) a ``name`` is specified, even if an explicit
+        ``token`` was provided to the service constructor. The account will be selected based on
+        the following criteria:
+
+        - If a ``filename`` is specified, account details will be loaded from ``filename``,
+          else they will be loaded from the default configuration file.
+
+        - If a ``name`` is specified, the corresponding account details will be loaded from
+          the configuration file, including ``channel``, ``token``, ``instance``, ``region``,
+          ``plans_preference``, and the advanced configuration parameters: ``url``,
+          ``url_resolver``, ``private_endpoint``,  ``verify``, and  ``proxies``.
+          **Important Note**: An explicit ``instance`` value provided during instantiation
+          will **overwrite** the value of the loaded ``instance``.
+
+        - If no ``name`` is specified: if ``channel`` is specified, the service will load the
+          default account associated with that channel from the configuration file. Else,
+          it will fall back to the overall default account, defined when calling :meth:`.save_account`
+          with ``set_as_default=True``.
 
         Args:
-            Optional[ChannelType] channel: Channel type. ``ibm_cloud``,
-                ``ibm_quantum_platform`` or ``local``.
+            Optional[ChannelType] channel: String that identifies the service platform. This is
+                set to ``ibm_quantum_platform`` by default, but can additionally take ``local``
+                and ``ibm_cloud`` as values.
                 If ``local`` is selected, the local testing mode will be used, and
                 primitive queries will run on a local simulator. For more details, check the
                 `Qiskit Runtime local testing mode
                 <https://quantum.cloud.ibm.com/docs/guides/local-testing-mode>`_  documentation.
-            Optional[str] token: IBM Cloud API key.
-            Optional[str] url: The API URL.
-                Defaults to https://quantum-computing.cloud.ibm.com (``ibm_cloud``),
-                https://quantum.cloud.ibm.com  (``ibm_quantum_platform``) or
+                For non-local modes, the channel is used to resolve the default API URL value.
+                ``ibm_cloud`` was the identifier for the legacy IBM Cloud platform, and
+                its url will be redirected to the new ``ibm_quantum_platform`` url.
+            Optional[str] token: IBM Cloud API key. Providing an API key is required for IQP
+                authentication. If not provided explicitly, the default saved account will be
+                queried for this API key.
+            Optional[str] url: The API URL. Defaults to different values depending on the selected
+                channel:  https://quantum.cloud.ibm.com  (``ibm_quantum_platform``), or
+                https://quantum-computing.cloud.ibm.com (``ibm_cloud``).
             Optional[str] filename: Full path of the file where the account is created.
-                Default: _DEFAULT_ACCOUNT_CONFIG_JSON_FILE
-            Optional[str] name: Name of the account to load.
+                Default: _DEFAULT_ACCOUNT_CONFIG_JSON_FILE.
+            Optional[str] name: Name of the account to load from file.
             Optional[str] instance: The service instance to use.
                 For ``ibm_cloud`` and ``ibm_quantum_platform``, this is the Cloud Resource
-                Name (CRN) or the service name. If set, it will define a default instance for
+                Name (CRN) or the service name. If set, it will define an instance for
                 service instantiation, if not set, the service will fetch all instances accessible
-                within the account.
+                within the account following the specified filtering criteria.
             Optional[dict] proxies: Proxy configuration. Supported optional keys are
                 ``urls`` (a dictionary mapping protocol or protocol and host to the URL of the proxy,
                 documented at https://requests.readthedocs.io/en/latest/api/#requests.Session.proxies),
@@ -124,15 +165,20 @@ def __init__(
             Optional[bool] verify: Whether to verify the server's TLS certificate.
             Optional[bool] private_endpoint: Connect to private API URL.
             Optional[Callable] url_resolver: Function used to resolve the runtime url.
-            Optional[str] region: Set a region preference. Accepted values are ``us-east`` or ``eu-de``.
+            Optional[str] region: Set a region preference for automatic instance selection.
+                This argument is **ignored** if an ``instance`` is specified.
+                Accepted values are ``us-east`` or ``eu-de``.
                 An instance with this region will be prioritized if an instance is not passed in.
             Optional[List[str]] plans_preference: A list of account plan names
-                (``open``, ``premium``, etc.), ordered by preference. An instance with the first
-                value in the list will be prioritized and only instances
-                with the given plan names will be considered. For example, if you want to avoid
-                using your premium accounts you can just pass in ``"open"`` to only use your open plan
-                instances. ``plans_preference`` is ignored if an ``instance`` is specified.
-            Optional[List[str]] tags: Set a list of tags to filter available instances.
+                ordered by priority for automatic instance selection.
+                This argument is **ignored** if an ``instance`` is specified.
+                Only instances with the given plan names will be considered.
+                For example, if you want to avoid using your premium accounts you can just
+                pass in ``"open"`` to only use your open plan instances.
+                Accepted values include (but are not limited to): ``open``, ``premium``,
+                ``flex``, ``on-prem``, ``pay-as-you-go``.
+            Optional[List[str]] tags: Set a list of tags to filter available instances for automatic
+                instance selection. This argument is **ignored** if an ``instance`` is specified.
 
         Returns:
             An instance of QiskitRuntimeService or QiskitRuntimeLocalService for local channel.