Add code examples to lib.rs

[austin-denoble]

Problem

We got feedback from @spacejam that it would be nice to add more detailed documentation and code examples to the top level lib.rs file to improve what people are shown when they hit the create on docs.rs: https://docs.rs/pinecone-sdk/latest/pinecone_sdk/index.html

Solution

I'm still pretty new to Rust and getting my bearings with a lot of things. Any feedback around best practices for presenting code or information through the crate and rustdoc, please let me know.

• Added some minimal code examples to the top level lib.rs file focused on some of the basic operations that can be done with the client.
• The README.md code examples were a bit out of date with some changes we've made - also did some clean up in there.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update
• Infrastructure change (CI configs, etc)
• Non-code change (docs, etc)
• None of the above: (explain here)

Test Plan

I tested all of the code added to lib.rs in a local project, so I at least know it runs and compiles.

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1208036142785509

[austin-denoble]

The spam of line breaks in here seems like it's from my vscode format-on-save settings. I think adding the spaces in is helpful visually.

[austin-denoble]

I think most of the code examples in here need this update. I can't remember if the types were originally exported from the modules and that was changed, but I needed to write things differently when I was testing locally.

[austin-denoble]

Just moved these up to group the public stuff together.

[haruska]

This is good cleanup. A benefit to having the examples in lib.rs is you can actually run the examples and add assert! statements to them as a part of cargo tests. That way they never get out of date.

The README.md shows up on crates.io: https://crates.io/crates/pinecone-sdk

The lib.rs docs show up on docs.rs: https://docs.rs/pinecone-sdk/latest/pinecone_sdk/

We might want to consider just linking to docs.rs in the README for most of the code examples and keep the example code docs in lib.rs as a part of the CI cargo tests to ensure the examples continue to work.

A good example might be axum:

• axum lib.rs rendered on axum docs.rs
• axum readme rendered on axum crates.io

[haruska]

Good cleanup. See previous comment for consideration.

[austin-denoble]

Good cleanup. See previous comment for consideration.

Appreciate the callouts, I agree regarding following up and moving our code examples into the lib.rs explicitly. Created a ticket for tracking.