Skip to content

Commit 1235fbd

Browse files
Fix minor README docs issues in client reference (#316)
## Problem @haruska pointed out that the headers in the SDK client reference navigation bar were a little off for "Create Index" showing "Create a pod index" only. The formatting also felt a bit off with everything being aligned. https://sdk.pinecone.io/python/pinecone.html While fixing this I also noticed the link for the `CONTRIBUTING.md` file is relative in the README, which doesn't work when linking from our generated docs. ## Solution - Promote "Indexes" to a top-level section to visually break up the nav list a bit, and then swap `Create Index` to the header and moving `Create a serverless index` and `Create a pod index` to sub-headers of that. - Link directly to github for the `CONTRIBUTING.md` file. ## Type of Change - [x] Non-code change (docs, etc) ## Test Plan |Before|After| | ------------- | ------------- | |<img width="1166" alt="Screenshot 2024-02-23 at 12 55 08 PM" src="https://github.com/pinecone-io/pinecone-python-client/assets/119623786/ba6f27b9-4844-4952-9886-7ab820f25196">|<img width="1170" alt="Screenshot 2024-02-23 at 12 55 32 PM" src="https://github.com/pinecone-io/pinecone-python-client/assets/119623786/f9ccfe8a-dce4-440a-b1f6-14bb3e78000e">| You can pull this branch down and build the docs locally. You'll need to make sure to install the grpc extras with poetry: ``` poetry install --extras "grpc" poetry run pdoc pinecone '!pinecone.core' '!pinecone.utils' --favicon ./favicon-32x32.png --docformat google -o ./docs ``` This will build the docs in the `/docs` folder under the project folder. You can open the `index.html` file locally.
1 parent e257894 commit 1235fbd

File tree

1 file changed

+17
-24
lines changed

1 file changed

+17
-24
lines changed

README.md

Lines changed: 17 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
# Pinecone Python Client &middot; ![License](https://img.shields.io/github/license/pinecone-io/pinecone-python-client?color=orange) [![CI](https://github.com/pinecone-io/pinecone-python-client/actions/workflows/merge.yaml/badge.svg)](https://github.com/pinecone-io/pinecone-python-client/actions/workflows/merge.yaml)
22

3-
43
The official Pinecone Python client.
54

65
For more information, see the docs at https://www.pinecone.io/docs/
@@ -10,24 +9,20 @@ For more information, see the docs at https://www.pinecone.io/docs/
109
- If you are upgrading from a `2.2.x` version of the client, check out the [**v3 Migration Guide**](https://canyon-quilt-082.notion.site/Pinecone-Python-SDK-v3-0-0-Migration-Guide-056d3897d7634bf7be399676a4757c7b#a21aff70b403416ba352fd30e300bce3).
1110
- [**Reference Documentation**](https://sdk.pinecone.io/python/index.html)
1211

13-
1412
### Example code
1513

1614
Many of the brief examples shown in this README are using very small vectors to keep the documentation concise, but most real world usage will involve much larger embedding vectors. To see some more realistic examples of how this client can be used, explore some of our many Jupyter notebooks in the [examples](https://github.com/pinecone-io/examples) repository.
1715

18-
1916
## Prerequisites
2017

2118
The Pinecone Python client is compatible with Python 3.8 and greater.
2219

23-
2420
## Installation
2521

2622
There are two flavors of the Pinecone python client. The default client installed from PyPI as `pinecone-client` has a minimal set of dependencies and interacts with Pinecone via HTTP requests.
2723

2824
If you are aiming to maximimize performance, you can install additional gRPC dependencies to access an alternate client implementation that relies on gRPC for data operations. See the guide on [tuning performance](https://docs.pinecone.io/docs/performance-tuning).
2925

30-
3126
### Installing with pip
3227

3328
```shell
@@ -78,9 +73,9 @@ pc = Pinecone() # This reads the PINECONE_API_KEY env var
7873

7974
#### Using a configuration object
8075

81-
If you prefer to pass configuration in code, for example if you have a complex application that needs to interact with multiple different Pinecone projects, the constructor accepts a keyword argument for `api_key`.
76+
If you prefer to pass configuration in code, for example if you have a complex application that needs to interact with multiple different Pinecone projects, the constructor accepts a keyword argument for `api_key`.
8277

83-
If you pass configuration in this way, you can have full control over what name to use for the environment variable, sidestepping any issues that would result
78+
If you pass configuration in this way, you can have full control over what name to use for the environment variable, sidestepping any issues that would result
8479
from two different client instances both needing to read the same `PINECONE_API_KEY` variable that the client implicitly checks for.
8580

8681
Configuration passed with keyword arguments takes precedent over environment variables.
@@ -109,15 +104,15 @@ index.upsert(vectors=[])
109104
index.query(vector=[...], top_key=10)
110105
```
111106

112-
## Indexes
107+
# Indexes
113108

114-
### Create Index
109+
## Create Index
115110

116-
#### Create a serverless index
111+
### Create a serverless index
117112

118113
> [!WARNING]
119114
> Serverless indexes are in **public preview** and are available only on AWS in the
120-
> `us-west-2` region. Check the [current limitations](https://docs.pinecone.io/docs/limits#serverless-index-limitations) and test thoroughly before using it in production.
115+
> `us-west-2` region. Check the [current limitations](https://docs.pinecone.io/docs/limits#serverless-index-limitations) and test thoroughly before using it in production.
121116
122117
```python
123118
from pinecone import Pinecone, ServerlessSpec
@@ -134,7 +129,7 @@ pc.create_index(
134129
)
135130
```
136131

137-
## Create a pod index
132+
### Create a pod index
138133

139134
The following example creates an index without a metadata
140135
configuration. By default, Pinecone indexes all metadata.
@@ -144,17 +139,17 @@ from pinecone import Pinecone, PodSpec
144139

145140
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
146141
pc.create_index(
147-
name="example-index",
148-
dimension=1536,
149-
metric="cosine",
142+
name="example-index",
143+
dimension=1536,
144+
metric="cosine",
150145
spec=PodSpec(
151-
environment='us-west-2',
146+
environment='us-west-2',
152147
pod_type='p1.x1'
153148
)
154149
)
155150
```
156151

157-
Pod indexes support many optional configuration fields. For example,
152+
Pod indexes support many optional configuration fields. For example,
158153
the following example creates an index that only indexes
159154
the "color" metadata field. Queries against this index
160155
cannot filter based on any other metadata field.
@@ -172,8 +167,8 @@ pc.create_index(
172167
"example-index-2",
173168
dimension=1536,
174169
spec=PodSpec(
175-
environment='us-west-2',
176-
pod_type='p1.x1',
170+
environment='us-west-2',
171+
pod_type='p1.x1',
177172
metadata_config=metadata_config
178173
)
179174
)
@@ -242,7 +237,6 @@ index = pc.Index(host=os.environ.get('INDEX_HOST'))
242237
index_stats_response = index.describe_index_stats()
243238
```
244239

245-
246240
## Upsert vectors
247241

248242
The following example upserts vectors to `example-index`.
@@ -356,7 +350,7 @@ from pinecone import Pinecone
356350
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
357351

358352
pc.create_collection(
359-
name="example-collection",
353+
name="example-collection",
360354
source="example-index"
361355
)
362356
```
@@ -398,7 +392,6 @@ pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
398392
pc.delete_collection("example-collection")
399393
```
400394

401-
# Contributing
402-
403-
If you'd like to make a contribution, or get setup locally to develop the Pinecone python client, please see our [contributing guide](./CONTRIBUTING.md)
395+
# Contributing
404396

397+
If you'd like to make a contribution, or get setup locally to develop the Pinecone python client, please see our [contributing guide](https://github.com/pinecone-io/pinecone-python-client/blob/main/CONTRIBUTING.md)

0 commit comments

Comments
 (0)