From 344f5ef5fbb9dff233697cd345b446fc5e21b4ce Mon Sep 17 00:00:00 2001 From: Panos Vagenas <35837085+vagenas@users.noreply.github.com> Date: Wed, 19 Jul 2023 13:07:24 +0200 Subject: [PATCH] docs: reflect new profile setup Signed-off-by: Panos Vagenas <35837085+vagenas@users.noreply.github.com> --- README.md | 8 +-- docs/getting_started/index.md | 20 +++---- docs/guide/cli_plugins.md | 7 +-- docs/guide/configuration.md | 107 ++++++++++++++++++---------------- docs/guide/data_indices.md | 8 +-- docs/guide/kgs.md | 6 +- docs/guide/projects.md | 7 +-- 7 files changed, 81 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index a615cf84..5f33e6b6 100644 --- a/README.md +++ b/README.md @@ -53,14 +53,14 @@ Python 3.8+ ## Start using the toolkit -### Login to Deep Search -For details, check the [authentication docs](https://ds4sd.github.io/deepsearch-toolkit/getting_started/#authentication). +### Set up a profile +For details, check [Profiles](https://ds4sd.github.io/deepsearch-toolkit/guide/configuration#profiles). ```console -deepsearch login +deepsearch profile config ``` ### Convert a document -For details, check the [document conversion docs](https://ds4sd.github.io/deepsearch-toolkit/guide/convert_doc). +For details, check [Document conversion](https://ds4sd.github.io/deepsearch-toolkit/guide/convert_doc). ```console deepsearch documents convert -p 1234567890abcdefghijklmnopqrstvwyz123456 -u https://arxiv.org/pdf/2206.00785.pdf ``` diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index 2e2f2151..904d95d2 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -6,31 +6,26 @@ After registering with [Deep Search](https://ds4sd.github.io/), you can obtain y --- -### Configure a profile +### Set up a profile === "CLI" - Configure a profile using [`deepsearch profile config`](../cli-reference.md#profile). + Set up a [profile][profiles] using `deepsearch profile config`. In its basic form it looks like this:
```console $ deepsearch profile config - - Host: # (1) - Username: # (2) - Api key: # (3) + Host: https://ds.example.com # the Deep Search instance you are using + Username: name@example.com # your username + Api key: (hidden) # your API key ```
- 1. Input the Deep Search deployment host to use. - 2. Enter your `User name`. - 3. Enter your `API key`. - 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 details, check [Profiles](../guide/configuration.md#profiles). + For details, check [Profiles][profiles]. ### Validate the setup @@ -89,3 +84,6 @@ Here, we show a simple way to convert documents using [Deep Search](https://ds4s ``` --- + + +[profiles]: ../guide/configuration.md#profiles diff --git a/docs/guide/cli_plugins.md b/docs/guide/cli_plugins.md index 61ec325d..a14deefa 100644 --- a/docs/guide/cli_plugins.md +++ b/docs/guide/cli_plugins.md @@ -83,12 +83,9 @@ Options: --help Show this message and exit. Commands: - config Manage CLI config files - cps Interact with DeepSearch CPS component + [ ... ] [ ... ] example - login Login to DeepSearch platform - query Interact with DeepSearch Query component - version Print the client and server version information + [ ... ] [ ... ]] ``` And running our newly added command gives us... diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 8b265c28..40c02da2 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -8,6 +8,10 @@ Besides *global* settings, the Toolkit also allows the configuration of multiple ## Profiles +The Toolkit provides the capability of easily interacting with different Deep Search +instances through the use of *profiles*. A user may define multiple profiles, identified +by profile name, and can easily switch between them. + ### Overview For an overview of the profile management commands check `deepsearch profile --help`: @@ -32,8 +36,8 @@ $ deepsearch profile --help ### 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`). +To set up a profile use `deepsearch profile config`, providing options as needed (for a +full reference check `deepsearch profile config --help`). Here is a basic invocation example: @@ -44,59 +48,60 @@ 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. +> NOTE: If you 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" - ``` - ---- +#### Usage in 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" +``` + +#### Usage in Python + +To use the active profile (recommended usage pattern): +```python +from deepsearch.cps.client.api import CpsApi +api = CpsApi.from_env() + +print([p.name for p in api.projects.list()]) +# -> outputs projects corresponding to active profile +``` + +To use a specific profile: +```python +from deepsearch.cps.client.api import CpsApi + +api = CpsApi.from_env(profile_name="foo") + +print([p.name for p in api.projects.list()]) +# -> outputs projects corresponding to "foo" +``` ## Environment variables diff --git a/docs/guide/data_indices.md b/docs/guide/data_indices.md index 12394ecc..8cb140ea 100644 --- a/docs/guide/data_indices.md +++ b/docs/guide/data_indices.md @@ -22,7 +22,7 @@ Suppose you want to create an index called `NAME`. Optionally, a description,`DE === "Python" - After you have generated the api object (from [login configuration](../installation/login.md)), + After you have generated the api object (from a [profile](../configuration#usage-in-python)): ```python api.data_indices.create(proj_key=PROJ_KEY, name=NAME, desc=DESC) @@ -159,9 +159,9 @@ Attachments can be added to an index item in a project. Briefly, attachments hav attachment_key = "usr_my_attachment" # optional. if set need start with 'usr_' and be snake_case index.add_item_attachment( - api=api, - index_item_id=index_item_id, - attachment_path=attachment_path, + api=api, + index_item_id=index_item_id, + attachment_path=attachment_path, attachment_key=attachment_key, # optional ) ``` diff --git a/docs/guide/kgs.md b/docs/guide/kgs.md index f3e1ab02..6c862855 100644 --- a/docs/guide/kgs.md +++ b/docs/guide/kgs.md @@ -64,7 +64,7 @@ More example queries are available in the [examples gallery](../gallery/index.md $ deepsearch cps kgs download -p 'abc123' -k 'zxc987' url - -------------------------------- + -------------------------------- https://host.domain/download-url ``` @@ -72,7 +72,7 @@ More example queries are available in the [examples gallery](../gallery/index.md === "Python" - After you have generated the `api` object (from [login configuration](../getting_started/#authentication)) + After you have generated the `api` object (from a [profile](../configuration#usage-in-python)): ```python proj_key = "abc123" # get your proj_key from the UI details @@ -80,4 +80,4 @@ More example queries are available in the [examples gallery](../gallery/index.md kg = api.knowledge_graphs.get(proj_key, kg_key) download_url = kg.download() - ``` \ No newline at end of file + ``` diff --git a/docs/guide/projects.md b/docs/guide/projects.md index cc3be43d..17da0fe8 100644 --- a/docs/guide/projects.md +++ b/docs/guide/projects.md @@ -17,8 +17,7 @@ A collaborator may be added to a project as `owner`, `editor`, or `viewer`. Belo ## Project management !!! info - Make sure to [configure your login](../getting_started/index.md#authentication) before - using the project management features listed below. + Make sure to [complete your profile setup](../getting_started/index.md#set-up-a-profile) before using the project management features listed below. ### Creating a project @@ -39,7 +38,7 @@ A collaborator may be added to a project as `owner`, `editor`, or `viewer`. Belo === "Python" - After you have generated the `api` object (from [login configuration](../getting_started/#authentication)), creating a project is very easy. + After you have generated the `api` object (from a [profile](../configuration#usage-in-python)), creating a project is very easy. ```python proj = api.projects.create(name="my-project") @@ -70,7 +69,7 @@ A collaborator may be added to a project as `owner`, `editor`, or `viewer`. Belo === "Python" - After you have generated the `api` object (from [login configuration](../getting_started/#authentication)), listing projects is very easy. + After you have generated the `api` object (from a [profile](../configuration#usage-in-python)), listing projects is very easy. ```python projects = api.projects.list() # returns list of projects