Corrected Docs code examples (#134)

Co-authored-by: Glenn Jocher <glenn.jocher@ultralytics.com>

docs/dataset.md

@@ -17,6 +17,11 @@ Let's dive in! 🚀
 Looking for a specific dataset? Fetch it rapidly using its unique ID with the code snippet below. This will let you access essential information, including its data.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 # Fetch a dataset by ID
 dataset = client.dataset('<Dataset ID>')  # Replace with your actual Dataset ID
 print(dataset.data)  # This prints the dataset information
@@ -27,7 +32,10 @@ print(dataset.data)  # This prints the dataset information
 Ready to start a new project? Follow the steps below to create a fresh dataset. All you need is to define a friendly name for your dataset and use the `create_dataset` method.
 
 ```python
-# Import client library comes before this snippet
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
 
 # Define your dataset properties
 data = {"meta": {"name": "My Dataset"}}  # Replace 'My Dataset' with your desired dataset name
@@ -43,6 +51,11 @@ print("Dataset created successfully!")
 As projects evolve, so should your datasets. If you need to modify your dataset's metadata, it's as simple as running the following code with the new details.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 # Obtain the dataset
 dataset = client.dataset("<Dataset ID>")  # Insert the correct Dataset ID
 
@@ -56,6 +69,11 @@ print("Dataset updated with new information.")
 If you ever need to remove a dataset, whether to declutter your workspace or because it's no longer needed, you can permanently delete it by invoking the `delete` method as shown here.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 # Select the dataset by its ID
 dataset = client.dataset('<Dataset ID>')  # Ensure the Dataset ID is specified
 
@@ -69,6 +87,11 @@ print("Dataset has been deleted.")
 To browse through your datasets or find the one you need, you can list all your datasets with pagination. It is helpful when dealing with a large number of datasets.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 # Retrieve the first page of datasets
 dataset = client.dataset_list(page_size=10)
 print("Current dataset:", dataset.results)  # Show the datasets on the current page
@@ -87,9 +110,13 @@ print("Previous page result:", dataset.results)
 This convenient function fetches a URL for dataset storage access, making it a breeze to download dataset files or artifacts stored remotely.
 
 ```python
-# Define the dataset ID for which you want a download link
-datasetId = "<Dataset ID>"  # Don't forget to replace this with the actual dataset ID
-dataset = client.dataset(datasetId)
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
+# Define the dataset ID for which you want a download link 
+dataset = client.dataset("<Dataset ID>")    # Don't forget to replace Dataset ID with the actual dataset ID
 
 # Retrieve the URL for downloading dataset contents
 url = dataset.get_download_link()
@@ -101,11 +128,13 @@ print("Download URL:", url)
 Uploading your dataset is a straightforward process. Set your dataset's ID and the file path you wish to upload, then utilize the `upload_dataset` function as detailed below.
 
 ```python
-# Set your dataset ID
-dataset_id = "<Dataset ID>"  # Substitute with the real dataset ID
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
 
 # Select the dataset
-dataset = client.dataset(dataset_id)
+dataset = client.dataset("<Dataset ID>")    # Substitute with the real dataset ID
 
 # Upload the dataset file
 dataset.upload_dataset(file="<Dataset File>")  # Make sure to specify the correct file path

docs/index.md

@@ -20,7 +20,7 @@ Ready to hit the ground running with the HUB-SDK? Our quickstart guide offers a
 
 Gain access to the latest stable release of HUB-SDK through PyPI. Simply execute the command below in your terminal/shell to seamlessly add the SDK to your Python project:
 
-```sh
+```bash
 pip install hub-sdk
 ```
 
@@ -34,8 +34,10 @@ Integration with Ultralytics services starts with the initialization of an `HUBC
 To utilize the simplicity of an API key, prepare a dictionary with your key like so:
 
 ```python
-credentials = {"api_key": "<YOUR-API-KEY>"}
+from hub_sdk import HUBClient
+
 # Replace <YOUR-API-KEY> with the actual key provided to you by Ultralytics.
+credentials = {"api_key": "<YOUR-API-KEY>"}
 ```
 
 By using an API key, you're choosing a common authentication method suitable for programmatic access. It's perfect for scenarios where integrating a key directly into your framework is desired for swift and secure service interaction.
@@ -44,19 +46,36 @@ By using an API key, you're choosing a common authentication method suitable for
 Prefer to harness your account credentials? Configure the `HUBClient` with your email and password in the credentials dictionary:
 
 ```python
-credentials = {"email": "<YOUR-EMAIL>", "password": "<YOUR-PASSWORD>"}
+from hub_sdk import HUBClient
+
 # Replace <YOUR-EMAIL> with your email address and <YOUR-PASSWORD> with your password.
+credentials = {"email": "<YOUR-EMAIL>", "password": "<YOUR-PASSWORD>"}
 ```
 
 Employing your email and password is a convenient choice if you're looking for a traditional login experience or aiming to utilize personalized features tied to your Ultralytics account.
 
 ### Bringing it All Together
 Now that your credentials are prepared, initiate your `HUBClient`:
 
-```python
-client = HUBClient(credentials)
-# The HUBClient is now initialized with your chosen authentication method.
-```
+!!! Example "HUB SDK Authentication"
+
+    === "Authentication with API Key"
+
+        ```python
+        from hub_sdk import HUBClient
+
+        credentials = {"api_key": "<YOUR-API-KEY>"} # api key
+        client = HUBClient(credentials)
+        ```
+
+    === "Authentication with Email and Password"
+
+        ```python
+        from hub_sdk import HUBClient
+
+        credentials = {"email": "<YOUR-EMAIL>", "password": "<YOUR-PASSWORD>"}  # email and password
+        client = HUBClient(credentials)
+        ```
 
 This crucial line of code crafts a new instance of the HUBClient, connecting you to the vast landscape of services offered by the Ultralytics platform. With your authentication details securely in place, you're all set to explore the functionalities at your fingertips!
 

docs/model.md

@@ -13,6 +13,11 @@ Welcome to the Ultralytics HUB-SDK Model Management documentation! Whether you'r
 In machine learning workflows, you often need to access a specific model. With Ultralytics HUB-SDK, fetching a model by its ID is a breeze. This essential function sets up a model object based on the provided unique identifier, granting you full access to the model's details and operations.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 model = client.model("<Model ID>")
 print(model.data)  # Outputs the model's metadata and configuration
 ```
@@ -22,6 +27,11 @@ print(model.data)  # Outputs the model's metadata and configuration
 Prior to model creation or training, ensuring the presence of both a project and a dataset is crucial. This straightforward code snippet helps you verify these components are available by initializing their objects. While utilizing a project and dataset for organizing model training is beneficial, it's important to note that it is not mandatory. If either ID is missing, the object data (`project.data`, `dataset.data`) will  be empty.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 project = client.project("<Project ID>")
 dataset = client.dataset("<Dataset ID>")
 ```
@@ -31,6 +41,11 @@ dataset = client.dataset("<Dataset ID>")
 Creating a new model tailored to your project requirements is made simple with this convenient function. Specify the model's name and associate it with your project and dataset. You can also customize configurations to fit your needs, such as setting the batch size or device, among others. Note that `projectId` and `datasetId` parameters are optional if you're not ready to tie the model to a project or dataset yet.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 data = {
     "meta": {"name": "sdk model"},  # Give your model a recognizable name
     "projectId": project.id,        # Associate with an existing project
@@ -53,6 +68,11 @@ model.create_model(data)  # Creates the model with your specified details
 As projects develop, you might need to update a model's metadata, such as renaming it for clarity. The SDK provides a method to refresh these details effortlessly, minimizing manual errors and saving you precious time.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 model = client.model("<Model ID>")
 model.update({"meta": {"name": "Updated Model Name"}})  # Renames the specified model
 ```
@@ -62,7 +82,12 @@ model.update({"meta": {"name": "Updated Model Name"}})  # Renames the specified
 Deleting a model is irreversible, so this function should be used with caution. When you're sure you want to remove a model from the system, the following command will permanently delete the specified model, along with all its associated data.
 
 ```python
-model = client.model("Model ID")
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
+model = client.model("<Model ID>")
 model.delete(hard=True)  # Permanently deletes the specified model
 ```
 By default, the delete method performs a soft delete, marking the model as inactive without removing it permanently. If you want to perform a hard delete and remove the model along with its associated data permanently, you can pass the argument hard=True as shown in the example above. Exercise caution when using the hard delete option, as it is irreversible and results in the complete removal of the specified model from the system.
@@ -72,6 +97,11 @@ By default, the delete method performs a soft delete, marking the model as inact
 Ultralytics HUB-SDK streamlines the task of fetching lists of models, while implementing pagination to efficiently navigate through potentially large collections of models. By customizing arguments such as `page_size`, you can tailor the output to your needs, including the ability to view both private and public projects.
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
 model_list = client.model_list(page_size=10)  # Fetches the first page with 10 models
 print("Current result:", model_list.results)  # Displays the current page's models
 
@@ -87,8 +117,12 @@ print("Previous page result:", model_list.results)  # Displays the previous page
 To track and visualize your model's performance metrics throughout the training process, use this function to upload metrics such as loss and accuracy. This enables the continual monitoring of training progress and simplifies the analysis stage.
 
 ```python
-modelId = "<Model ID>"
-model = client.model(modelId)
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
+model = client.model("<Model ID>")
 
 # Define your metrics structure. Keys are steps, and values are JSON strings of metrics.
 data = {
@@ -105,8 +139,12 @@ model.upload_metrics(data)  # Uploads the specified metrics to the model
 Exporting models for various purposes such as deployment or in-depth analysis has never been easier. Specify the format you require, and this function will prepare the model accordingly. Whether you need a Tensorflow or a PyTorch format, the SDK handles it seamlessly.
 
 ```python
-modelId = "<Model ID>"
-model = client.model(modelId)
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
+model = client.model("<Model ID>")
 model.export(format="pyTorch")  # Exports the model as a PyTorch file
 ```
 
@@ -115,8 +153,12 @@ model.export(format="pyTorch")  # Exports the model as a PyTorch file
 Occasionally, you might require direct access to your model's remotely-stored artifacts. This convenient function provides a URL to access specific files like your best-performing model weights.
 
 ```python
-modelId = "<Model ID>"
-model = client.model(modelId)
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
+model = client.model("<Model ID>")
 weight_url = model.get_weights_url("best")  # Retrieves the URL for the model's optimal checkpoint weights. By default, it returns the URL for the best weights. To obtain the most recent weights, specify 'last.
 print("Weight URL link:", weight_url)  # Prints out the weight url link
 ```
@@ -126,8 +168,12 @@ print("Weight URL link:", weight_url)  # Prints out the weight url link
 Uploading a model checkpoint is made straightforward with the `upload_model` function. Simply indicate the significance of the checkpoint with the `is_best` flag and the training epoch for clarity.
 
 ```python
-model_id = "<Model ID>"
-model = client.model(model_id)
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"}
+client = HUBClient(credentials)
+
+model = client.model("<Model ID>")
 model.upload_model(is_best=True, epoch=5, weights="<Weight File>")  # Uploads the specified model checkpoint
 ```
 

docs/project.md

@@ -13,6 +13,11 @@ Welcome to the Ultralytics HUB-SDK documentation! Here we'll guide you through t
 When you already have a project hosted on the Ultralytics platform, you may want to retrieve it to see its details or make changes. To fetch a project by its unique ID, you only need to pass the ID to the `client.project` function. Below is a snippet that enables you to do just that, providing a quick peek at the project's data:
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"} # api key
+client = HUBClient(credentials)
+
 project = client.project('<Project ID>')  # Replace '<Project ID>' with your actual project ID
 print(project.data)
 ```
@@ -22,6 +27,11 @@ print(project.data)
 Are you starting a fresh ML project? Fantastic! The following Python code outlines the steps to create a new project on Ultralytics. We will import the necessary libraries, define the project details (in this case its name), and finally create the project using the `create_project` method of our HUB-SDK client library. Here's how:
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"} # api key
+client = HUBClient(credentials)
+
 data = {"meta": {"name": "my project"}}  # Name your project
 project = client.project()  # Initialize a project instance
 project.create_project(data)  # Create your new project with the specified data
@@ -32,6 +42,11 @@ project.create_project(data)  # Create your new project with the specified data
 Update your project's metadata with ease by specifying the project ID and the new details you want to include. This could be a name change, description update, or any other modifiable property. Find out how to execute these changes with this straightforward code snippet:
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"} # api key
+client = HUBClient(credentials)
+
 project = client.project('<Project ID>')  # Provide your actual project ID here
 project.update({"meta": {"name": "Project name update"}})  # Update the project's name or other metadata
 ```
@@ -41,6 +56,11 @@ project.update({"meta": {"name": "Project name update"}})  # Update the project'
 If you no longer require a project and wish to delete it from the Ultralytics platform, you can do so with a simple call to the `delete` method on the project object. The following snippet will guide you through deleting a project using its ID:
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"} # api key
+client = HUBClient(credentials)
+
 project = client.project("<Project ID>")  # Input the project ID for the project to delete
 project.delete()  # This will permanently delete your project
 ```
@@ -50,6 +70,11 @@ project.delete()  # This will permanently delete your project
 In some cases, you may want to browse through your projects or even check out public projects on Ultralytics. This can be done by fetching a list of projects with your desired page size. Our code snippet demonstrates how to view the current page results, navigate to the next page, and then go back to the previous one. It's a great way to explore the breadth of projects available:
 
 ```python
+from hub_sdk import HUBClient
+
+credentials = {"api_key": "<YOUR-API-KEY>"} # api key
+client = HUBClient(credentials)
+
 projects = client.project_list(page_size=10)  # Fetch a list of projects with specified page size
 print("Current result:", projects.results)  # Display the projects in the current page