From ce35d3acb420cb0c2bb0ad5e52000c0865066add Mon Sep 17 00:00:00 2001 From: Panos Vagenas <35837085+vagenas@users.noreply.github.com> Date: Tue, 18 Jul 2023 10:00:29 +0200 Subject: [PATCH] docs: add configuration docs Signed-off-by: Panos Vagenas <35837085+vagenas@users.noreply.github.com> --- deepsearch/core/cli/main.py | 2 +- deepsearch/core/cli/profile.py | 2 +- docs/getting_started/index.md | 2 +- docs/guide/configuration.md | 119 +++++++++++++++++++++++++++++++++ docs/guide/index.md | 4 ++ docs/index.md | 8 +-- mkdocs.yml | 1 + 7 files changed, 131 insertions(+), 7 deletions(-) create mode 100644 docs/guide/configuration.md diff --git a/deepsearch/core/cli/main.py b/deepsearch/core/cli/main.py index 4e6d1260..96129e21 100644 --- 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 index 7bb63572..71b81ded 100644 --- 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 index f9a5f9c2..2e2f2151 100644 --- 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 new file mode 100644 index 00000000..8b265c28 --- /dev/null +++ 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: name@example.com +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 index 0bc163b5..885bf761 100644 --- 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 index fb960463..46444cd1 100644 --- 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
```console -// Login to Deep Search, see authentication. -$ deepsearch login +// Set up a profile, see profiles. +$ deepsearch profile config ... // Convert a document diff --git a/mkdocs.yml b/mkdocs.yml index ea5fd93a..49f024f1 100644 --- 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