docs: add configuration docs

Signed-off-by: Panos Vagenas <[email protected]>
DS4SD · Jul 18, 2023 · ce35d3a · ce35d3a
1 parent 7c04879
commit ce35d3a
Show file tree

Hide file tree

Showing 7 changed files with 131 additions and 7 deletions.
diff --git a/deepsearch/core/cli/main.py b/deepsearch/core/cli/main.py
@@ -11,7 +11,7 @@
     add_completion=False,
     pretty_exceptions_enable=False,
 )
-app.add_typer(profile_app, name="profile", help="Manage DeepSearch SDK configuration")
+app.add_typer(profile_app, name="profile", help="Manage profile configuration")
 app.add_typer(login_app, name="login", help=MSG_LOGIN_DEPRECATION)
 
 

diff --git a/deepsearch/core/cli/profile.py b/deepsearch/core/cli/profile.py
@@ -83,7 +83,7 @@ def list_profiles() -> None:
 
 @app.command(
     name="show",
-    help=f"Displays a profile.",
+    help=f"Display a profile.",
 )
 @cli_handler()
 def show_profile(

diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
@@ -30,7 +30,7 @@ After registering with [Deep Search](https://ds4sd.github.io/), you can obtain y
     By providing a profile name (via option `--profile-name`) you can configure multiple
     different profiles, which you can then easily switch between and manage.
 
-    For a complete reference, check [`deepsearch profile --help`](../cli-reference.md#profile).
+    For details, check [Profiles](../guide/configuration.md#profiles).
 
 ### Validate the setup
 

diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
@@ -0,0 +1,119 @@
+# Configuration
+
+The Toolkit can be configured both via the CLI and via
+environment variables.
+
+Besides *global* settings, the Toolkit also allows the configuration of multiple
+*profiles* for enabling users to easily work with different Deep Search deployments.
+
+## Profiles
+
+### Overview
+
+For an overview of the profile management commands check `deepsearch profile --help`:
+```console
+$ deepsearch profile --help
+
+ Usage: deepsearch profile [OPTIONS] COMMAND [ARGS]...
+
+ Manage profile configuration
+
+╭─ Options ──────────────────────────────────────────────────────╮
+│ --help          Show this message and exit.                    │
+╰────────────────────────────────────────────────────────────────╯
+╭─ Commands ─────────────────────────────────────────────────────╮
+│ config         Add or update a profile.                        │
+│ list           List all profiles.                              │
+│ remove         Remove a profile.                               │
+│ show           Display a profile.                              │
+│ use            Activate a profile.                             │
+╰────────────────────────────────────────────────────────────────╯
+```
+
+### Profile setup
+
+To setup a profile use [`deepsearch profile config`](../cli-reference.md#profile),
+providing options as needed (for a full reference run with `--help`).
+
+Here is a basic invocation example:
+
+```console
+$ deepsearch profile config
+Host: https://deepsearch-experience.res.ibm.com
+Username: [email protected]
+Api key:
+```
+
+> NOTE: If you had used the meanwhile deprecated `deepsearch login` command to set up a
+config file in the default location, that will automatically be migrated to a profile.
+
+### Usage
+
+Here some usage examples:
+
+=== "CLI"
+
+    ```console
+    $ # configure a profile
+    $ deepsearch profile config --profile-name foo --host ds-1.example.com ...
+    $ # -> "foo" now available and selected as the active profile
+    $
+    $ deepsearch cps projects list
+    $ # -> outputs projects corresponding to "foo"
+    $
+    $ # configure another profile
+    $ deepsearch profile config --profile-name bar --host ds-2.example.com ...
+    $ # -> "bar" now available and selected as the active profile
+    $
+    $ deepsearch profile list
+    $ # -> displays all profiles, with "bar" marked as the active one
+    $
+    $ deepsearch cps projects list
+    $ # -> outputs projects corresponding to "bar"
+    $
+    $ # switch to previous profile
+    $ deepsearch profile use foo
+    $ # -> "foo" now selected as the active profile
+    $
+    $ deepsearch cps projects list
+    $ # -> outputs projects corresponding to "foo"
+    ```
+
+=== "Python"
+
+    ```python
+    from deepsearch.cps.client.api import CpsApi
+
+    # using the active profile; let's assume that is "foo"
+    api = CpsApi.from_env()
+    print([p.name for p in api.projects.list()])
+    # -> outputs projects corresponding to "foo"
+
+    # using a profile by name
+    api = CpsApi.from_env(profile_name="bar")
+    print([p.name for p in api.projects.list()])
+    # -> outputs projects corresponding to "bar"
+    ```
+
+---
+
+
+## Environment variables
+
+Under the hood, configuration management in the Toolkit is implemented based on [Pydantic
+Settings with dotenv support](https://docs.pydantic.dev/1.10/usage/settings).
+
+Configuration is persisted in Toolkit-managed dotenv files, but can be overriden via
+environment variables.
+
+To see which environment variables are supported, check the relevant [Pydantic Settings
+classes][settings_file], also taking into account any defined prefixes.
+
+For example you can set the profile for the scope of a single operation (e.g. a project
+listing) as follows:
+
+```console
+DEEPSEARCH_PROFILE=bar deepsearch cps projects list
+```
+
+[settings_file]: https://github.com/DS4SD/deepsearch-toolkit/blob/main/deepsearch/core/client/settings.py
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -1,5 +1,9 @@
 # User guides
 
+## Configuration
+
+- [Configure the SDK](./configuration.md)
+
 ## Common Deep Search operations
 
 - [Convert a document](./convert_doc.md)

diff --git a/docs/index.md b/docs/index.md
@@ -8,7 +8,7 @@
 
 *Interact with the Deep Search platform for new knowledge explorations and discoveries*
 
-The Deep Search Toolkit is a Python SDK allowing a user to interact with the Deep Search platform. The Toolkit provides easy-to-use functionalities for several common processes such as document conversion, graph creation and querying.
+The Deep Search Toolkit provides a Python SDK and a CLI allowing a user to interact with the Deep Search platform. The Toolkit provides easy-to-use functionalities for several common processes such as document conversion, graph creation and querying.
 
 [Learn about IBM Deep Search :octicons-link-external-16:](https://ds4sd.github.io/){ .md-button }
 
@@ -24,7 +24,7 @@ The Deep Search Toolkit is a Python SDK allowing a user to interact with the Dee
 ## Install the Deep Search Toolkit
 
 The Deep Search Toolkit is available as a [PyPI package](https://pypi.org/project/deepsearch-toolkit/).
-It can be installed using the standard Python package managers like `pip`, `poetry`, etc. 
+It can be installed using the standard Python package managers like `pip`, `poetry`, etc.
 
 ### Requirements
 
@@ -49,8 +49,8 @@ $ pip install deepsearch-toolkit
 <div class="termy">
 
 ```console
-// Login to Deep Search, see <a href="https://ds4sd.github.io/deepsearch-toolkit/getting_started/#authentication">authentication</a>.
-$ deepsearch login
+// Set up a profile, see <a href="./guide/configuration#profiles">profiles</a>.
+$ deepsearch profile config
 ...
 
 // Convert a document

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -53,6 +53,7 @@ nav:
   - Getting started: getting_started/index.md
   - User guide:
       - "guide/index.md"
+      - Configuration: guide/configuration.md
       - Document conversion: guide/convert_doc.md
       - Projects: guide/projects.md
       - Data: guide/data_indices.md