Skip to content

Commit 0a7cb87

Browse files
vagenasvagenas
authored
docs: refactor docs and README (#153)
Signed-off-by: Panos Vagenas <[email protected]>
1 parent 1a7048e commit 0a7cb87

File tree

6 files changed

+60
-180
lines changed

6 files changed

+60
-180
lines changed

‎README.md

+8-51
Original file line numberDiff line numberDiff line change
@@ -5,75 +5,32 @@
55
[![License MIT](https://img.shields.io/github/license/ds4sd/deepsearch-toolkit)](https://opensource.org/licenses/MIT)
66
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
77
[![Docs](https://img.shields.io/badge/website-live-brightgreen)](https://ds4sd.github.io/deepsearch-toolkit/)
8-
[![Downloads](https://static.pepy.tech/badge/deepsearch-toolkit)](https://pepy.tech/project/deepsearch-toolkit)
8+
[![Downloads](https://static.pepy.tech/badge/deepsearch-toolkit/month)](https://pepy.tech/project/deepsearch-toolkit)
99

1010

1111
*Interact with the Deep Search platform for new knowledge explorations and discoveries*
1212

1313

14-
The Deep Search Toolkit is a Python SDK and CLI allowing users to interact with the Deep Search platform.
15-
The Toolkit provides easy-to-use functionalities for several common processes such as document conversion, graph creation and querying.
16-
17-
18-
[Learn about IBM Deep Search](https://ds4sd.github.io/)
14+
The Deep Search Toolkit is a Python SDK and CLI allowing users to interact with the [Deep Search](https://ds4sd.github.io) platform.
15+
The Toolkit provides easy-to-use features for several common document workflows such as conversion, graph creation, and querying, including semantic retrieval and RAG.
1916

2017

2118
## Quick links
2219

23-
- [Documentation](https://ds4sd.github.io/deepsearch-toolkit)
20+
- [Deep Search](https://ds4sd.github.io)
21+
- [Deep Search Toolkit](https://ds4sd.github.io/deepsearch-toolkit)
2422
- [Deep Search Examples](https://github.com/ds4sd/deepsearch-examples)
2523

2624

2725
## Install
2826

29-
To set up, just install `deepsearch-toolkit` with your packaging tool.
30-
31-
With [`poetry`](https://python-poetry.org):
32-
```console
33-
poetry add deepsearch-toolkit
34-
```
35-
36-
With `pip`:
37-
```console
27+
```shell
3828
pip install deepsearch-toolkit
3929
```
4030

41-
### Extras
42-
Optional functionality can be installed as package "extras". To install all extras, use
43-
`deepsearch-toolkit[all]` with your packaging tool.
44-
45-
### Install as toolkit developer
46-
If you are a Deep Search Toolkit developer, set up as follows:
47-
```console
48-
poetry install --all-extras
49-
```
50-
51-
### Requirements
31+
## Getting started
5232

53-
Python 3.8+
54-
55-
## Start using the toolkit
56-
57-
### Set up a profile
58-
For details, check [Profiles](https://ds4sd.github.io/deepsearch-toolkit/guide/configuration#profiles).
59-
```console
60-
deepsearch profile config
61-
```
62-
63-
### Convert a document
64-
For details, check [Document conversion](https://ds4sd.github.io/deepsearch-toolkit/guide/convert_doc).
65-
```console
66-
deepsearch documents convert -p 1234567890abcdefghijklmnopqrstvwyz123456 -u https://arxiv.org/pdf/2206.00785.pdf
67-
```
68-
69-
The output should look like:
70-
```
71-
Submitting input: : 100%|██████████████████████████████| 1/1 [00:01<00:00, 1.52s/it]
72-
Converting input: : 100%|██████████████████████████████| 1/1 [00:33<00:00, 33.80s/it]
73-
Downloading result: : 100%|██████████████████████████████| 1/1 [00:01<00:00, 1.11s/it]
74-
Total online documents 1
75-
Successfully converted documents 1
76-
```
33+
Check out [Getting started](https://ds4sd.github.io/deepsearch-toolkit/#getting-started).
7734

7835

7936
## Get help and support

‎docs/getting_started/index.md

-70
This file was deleted.

‎docs/guide/configuration.md

+6-20
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,11 @@ The Toolkit provides the capability of easily interacting with different Deep Se
1111
instances through the use of *profiles*. A user may define multiple profiles, identified
1212
by profile name, and can easily switch between them.
1313

14-
### Overview
14+
### Profile Setup
15+
16+
To configure your Deep Search profile, check out [Set up your Profile](../index.md#set-up-your-profile).
17+
18+
### Command Overview
1519

1620
For an overview of the profile management commands check `deepsearch profile --help`:
1721
```console
@@ -33,24 +37,6 @@ $ deepsearch profile --help
3337
╰────────────────────────────────────────────────────────────────╯
3438
```
3539

36-
### Profile setup
37-
38-
To set up a profile use `deepsearch profile config`, providing options as needed (for a
39-
full reference check `deepsearch profile config --help`).
40-
41-
Here is a basic invocation example:
42-
43-
```console
44-
$ deepsearch profile config
45-
Host: https://deepsearch-experience.res.ibm.com
46-
Username: [email protected]
47-
Api key:
48-
```
49-
50-
!!! note
51-
If you had used the meanwhile deprecated `deepsearch login` command to set up a
52-
config file in the default location, that will automatically be migrated to a profile.
53-
5440
### Usage
5541

5642
#### Usage in CLI
@@ -121,7 +107,7 @@ print([p.name for p in api.projects.list()])
121107
# -> outputs projects corresponding to provided settings
122108
```
123109

124-
## Environment variables
110+
## Environment Variables
125111

126112
Under the hood, the Toolkit leverages [Pydantic Settings with dotenv
127113
support][pydantic_settings], so configuration settings can be easily overriden via

‎docs/guide/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# User guides
1+
# User guide
22

33
## Configuration
44

‎docs/index.md

+43-35
Original file line numberDiff line numberDiff line change
@@ -5,64 +5,72 @@
55
[![License MIT](https://img.shields.io/github/license/ds4sd/deepsearch-toolkit)](https://opensource.org/licenses/MIT)
66
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
77
[![Docs](https://img.shields.io/badge/website-live-brightgreen)](https://ds4sd.github.io/deepsearch-toolkit/)
8+
[![Downloads](https://static.pepy.tech/badge/deepsearch-toolkit/month)](https://pepy.tech/project/deepsearch-toolkit)
89

910
*Interact with the Deep Search platform for new knowledge explorations and discoveries*
1011

1112
The Deep Search Toolkit is a Python SDK and CLI allowing users to interact with the Deep Search platform.
12-
The Toolkit provides easy-to-use functionalities for several common processes such as document conversion, graph creation and querying.
13+
The Toolkit provides easy-to-use features for several common document workflows such as conversion, graph creation, and querying, including semantic retrieval and RAG.
1314

15+
[Deep Search :octicons-link-external-16:](https://ds4sd.github.io/){ .md-button .md-button--primary }
16+
[Deep Search GitHub :octicons-link-external-16:](https://github.com/ds4sd/){ .md-button }
17+
[Examples :octicons-link-external-16:](https://github.com/DS4SD/deepsearch-examples){ .md-button }
1418

15-
[Learn about IBM Deep Search :octicons-link-external-16:](https://ds4sd.github.io/){ .md-button }
19+
## Getting Started
1620

21+
### Install
1722

18-
## Quick Links
23+
=== "pip"
1924

20-
[Deep Search](https://ds4sd.github.io/){ .md-button .md-button--primary }
21-
[Github](https://github.com/ds4sd/){ .md-button .md-button--primary }
22-
[Getting started](getting_started/index.md){ .md-button .md-button--primary }
23-
[Examples](https://github.com/DS4SD/deepsearch-examples){ .md-button .md-button--primary }
25+
```shell
26+
pip install deepsearch-toolkit
27+
```
2428

29+
=== "pipx"
2530

26-
## Install the Deep Search Toolkit
31+
```shell
32+
pipx install deepsearch-toolkit
33+
```
2734

28-
The Deep Search Toolkit is available as a [PyPI package](https://pypi.org/project/deepsearch-toolkit/).
29-
It can be installed using the standard Python package managers like `pip`, `poetry`, etc.
35+
=== "poetry"
3036

31-
### Requirements
37+
```shell
38+
poetry add deepsearch-toolkit
39+
```
3240

33-
Python 3.8+
41+
### Set up your Profile
3442

35-
### Install using pip
43+
After logging in to Deep Search, you can set up your profile as shown below:
3644

37-
<div class="termy">
45+
1. click on the *Toolkit / API* icon on the top-right corner
46+
2. from the *Toolkit* section, copy the command and run on your terminal
47+
3. when prompted for the API key, copy it from the *HTTP* section and complete the setup
3848

39-
```console
40-
$ pip install deepsearch-toolkit
49+
![Deep Search Authentication Info](../images/deepsearch-auth-info.png)
4150

42-
---> 100%
43-
```
51+
To quickly check your profile setup, run the following — your projects should be displayed:
4452

45-
</div>
53+
=== "CLI"
4654

55+
```shell
56+
deepsearch cps projects list
57+
```
4758

48-
### Start using the toolkit
59+
=== "Python"
4960

61+
```python
62+
import deepsearch as ds
63+
api = ds.CpsApi.from_env()
64+
print([p.name for p in api.projects.list()])
65+
```
5066

51-
<div class="termy">
67+
!!! info "Multi-profile support"
5268

53-
```console
54-
// Set up a profile, see <a href="./guide/configuration#profiles">profiles</a>.
55-
$ deepsearch profile config
56-
...
69+
You can set up multiple profiles, e.g. for different deployments. For details on managing profiles, check
70+
[Profiles](./guide/configuration.md#profiles).
5771

58-
// Convert a document
59-
// for more details, see <a href="https://ds4sd.github.io/deepsearch-toolkit/guide/convert_doc/">document conversion</a>.
60-
$ deepsearch documents convert -p 1234567890abcdefghijklmnopqrstvwyz123456 -u https://arxiv.org/pdf/2206.00785.pdf
61-
Submitting input: : 100%|██████████████████████████████| 1/1 [00:01<00:00, 1.52s/it]
62-
Converting input: : 100%|██████████████████████████████| 1/1 [00:33<00:00, 33.80s/it]
63-
Downloading result: : 100%|██████████████████████████████| 1/1 [00:01<00:00, 1.11s/it]
64-
Total online documents 1
65-
Successfully converted documents 1
66-
```
72+
### Start Using the Toolkit
6773

68-
</div>
74+
Check out [Deep Search Examples :octicons-link-external-16:](https://github.com/DS4SD/deepsearch-examples) for
75+
interactive notebooks showcasing various common usage scenarios and find inspiration on
76+
how to make the most out of your own documents.

‎mkdocs.yml

+2-3
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ theme:
5050

5151
nav:
5252
- Home: index.md
53-
- Getting started: getting_started/index.md
53+
- Examples [↗]: "https://github.com/DS4SD/deepsearch-examples"
5454
- User guide:
5555
- "guide/index.md"
5656
- Configuration: guide/configuration.md
@@ -60,7 +60,6 @@ nav:
6060
- Knowledge graphs: guide/kgs.md
6161
- APIs: guide/apis.md
6262
- Plugin system: guide/cli_plugins.md
63-
- Example gallery: "https://github.com/DS4SD/deepsearch-examples"
6463
- API reference:
6564
- Toolkit reference: api-reference.md
6665
- OpenAPI:
@@ -69,7 +68,7 @@ nav:
6968
- CLI reference: cli-reference.md
7069

7170
# Copyright
72-
copyright: Copyright &copy; 2023 <strong>IBM</strong> Research Europe – Deep Search team
71+
copyright: Copyright &copy; 2024 <strong>IBM</strong> Research Europe – Deep Search team
7372

7473
# Customization
7574
extra:

0 commit comments

Comments
 (0)