Write documentation (#152)

Author: qgallouedec

README.md

@@ -1,24 +1,23 @@
 <p align="center">
-
 <img width="75%" src="https://github.com/user-attachments/assets/6d6a41e7-fbc1-43ec-bda6-15f9ff4bd25c" />
-
-
 </p>
 
 `trackio` is a lightweight, free experiment tracking Python library built on top of Hugging Face Datasets and Spaces 🤗.
 
-
 ![Screen Recording 2025-07-28 at 5 26 32 PM](https://github.com/user-attachments/assets/f3eac49e-d8ee-4fc0-b1ca-aedfc6d6fae1)
 
+- **API compatible** with `wandb.init`, `wandb.log`, and `wandb.finish`. Drop-in replacement: just 
 
-- **API compatible** with `wandb.init`, `wandb.log`, and `wandb.finish` (drop-in replacement: just `import trackio as wandb`)
-- *Local-first* design: dashboard runs locally by default. You can also host it on Spaces by specifying a `space_id`.
+  ```python
+  import trackio as wandb
+  ```
+
+- **Local-first** design: dashboard runs locally by default. You can also host it on Spaces by specifying a `space_id`.
 - Persists logs locally (or in a private Hugging Face Dataset)
 - Visualize experiments with a Gradio dashboard locally (or on Hugging Face Spaces)
-- Everything here, including hosting on Hugging Faces, is **free**!
-
-Trackio is designed to be lightweight (the core codebase is <1,000 lines of Python code), not fully-featured. It is designed in an extensible way and written entirely in Python so that developers can easily fork the repository and add functionality that they care about.
+- Everything here, including hosting on Hugging Face, is **free**!
 
+Trackio is designed to be lightweight (the core codebase is <3,000 lines of Python code), not fully-featured. It is designed in an extensible way and written entirely in Python so that developers can easily fork the repository and add functionality that they care about.
 
 ## Installation
 
@@ -36,48 +35,51 @@ uv pip install trackio
 
 ## Usage
 
-The usage of `trackio` is designed to be a identical to `wandb` in most cases:
+To get started, you can run a simple example that logs some fake training metrics:
 
 ```python
-import trackio as wandb
+import trackio
 import random
 import time
 
 runs = 3
 epochs = 8
 
-def simulate_multiple_runs():
-    for run in range(runs):
-        wandb.init(project="fake-training", config={
-            "epochs": epochs,
-            "learning_rate": 0.001,
-            "batch_size": 64
+
+for run in range(runs):
+    trackio.init(
+        project="my-project",
+        config={"epochs": epochs, "learning_rate": 0.001, "batch_size": 64}
+    )
+
+    for epoch in range(epochs):
+        train_loss = random.uniform(0.2, 1.0)
+        train_acc = random.uniform(0.6, 0.95)
+
+        val_loss = train_loss - random.uniform(0.01, 0.1)
+        val_acc = train_acc + random.uniform(0.01, 0.05)
+
+        trackio.log({
+            "epoch": epoch,
+            "train_loss": train_loss,
+            "train_accuracy": train_acc,
+            "val_loss": val_loss,
+            "val_accuracy": val_acc
         })
-        
-        for epoch in range(epochs):
-            train_loss = random.uniform(0.2, 1.0)
-            train_acc = random.uniform(0.6, 0.95)
-    
-            val_loss = train_loss - random.uniform(0.01, 0.1)
-            val_acc = train_acc + random.uniform(0.01, 0.05)
-    
-            wandb.log({
-                "epoch": epoch,
-                "train_loss": train_loss,
-                "train_accuracy": train_acc,
-                "val_loss": val_loss,
-                "val_accuracy": val_acc
-            })
-    
-            time.sleep(0.2)
-
-    wandb.finish()
-
-simulate_multiple_runs()
+
+        time.sleep(0.2)
+
+trackio.finish()
 ```
 
 Running the above will print to the terminal instructions on launching the dashboard.
 
+The usage of `trackio` is designed to be a identical to `wandb` in most cases, so you can easily switch between the two libraries.
+
+```py
+import trackio as wandb
+```
+
 ## Dashboard
 
 You can launch the dashboard by running in your terminal:
@@ -97,30 +99,32 @@ trackio.show()
 You can also provide an optional `project` name as the argument to load a specific project directly:
 
 ```bash
-trackio show --project "my project"
+trackio show --project "my-project"
 ```
 
 or, in Python:
 
 ```py
 import trackio 
 
-trackio.show(project="my project")
+trackio.show(project="my-project")
 ```
 
 ## Deploying to Hugging Face Spaces
 
-When calling `trackio.init()`, by default the service will run locally and store project data on the local machine. 
+When calling `trackio.init()`, by default the service will run locally and store project data on the local machine.
 
 But if you pass a `space_id` to `init`, like:
 
 ```py
-trackio.init(project="fake-training", space_id="org_name/space_name")
-``` 
-or 
+trackio.init(project="my-project", space_id="orgname/space_id")
+```
+
+or
+
 ```py
-trackio.init(project="fake-training", space_id="user_name/space_name")
-``` 
+trackio.init(project="my-project", space_id="username/space_id")
+```
 
 it will use an existing or automatically deploy a new Hugging Face Space as needed. You should be logged in with the `huggingface-cli` locally and your token should have write permissions to create the Space.
 
@@ -130,11 +134,10 @@ One of the reasons we created `trackio` was to make it easy to embed live dashbo
 
 ![image](https://github.com/user-attachments/assets/77f1424b-737b-4f04-b828-a12b2c1af4ef)
 
-
 If you are hosting your Trackio dashboard on Spaces, then you can embed the url of that Space as an IFrame. You can even use query parameters to only specific projects and/or metrics, e.g.
 
 ```html
-<iframe src="https://abidlabs-trackio-1234.hf.space/?project=fake-training&metrics=train_loss,train_accuracy&sidebar=hidden" width=1600 height=500 frameBorder="0">
+<iframe src="https://abidlabs-trackio-1234.hf.space/?project=my-project&metrics=train_loss,train_accuracy&sidebar=hidden" width=1600 height=500 frameBorder="0">
 ```
 
 Supported query parameters:
@@ -146,9 +149,10 @@ Supported query parameters:
 ## Examples
 
 To get started and see basic examples of usage, see these files:
-* [Basic example of logging metrics locally](https://github.com/gradio-app/trackio/blob/main/examples/fake-training.py)
-* [Persisting metrics in a Hugging Face Dataset](https://github.com/gradio-app/trackio/blob/main/examples/persist-dataset.py)
-* [Deploying the dashboard to Spaces](https://github.com/gradio-app/trackio/blob/main/examples/deploy-on-spaces.py)
+
+- [Basic example of logging metrics locally](https://github.com/gradio-app/trackio/blob/main/examples/fake-training.py)
+- [Persisting metrics in a Hugging Face Dataset](https://github.com/gradio-app/trackio/blob/main/examples/persist-dataset.py)
+- [Deploying the dashboard to Spaces](https://github.com/gradio-app/trackio/blob/main/examples/deploy-on-spaces.py)
 
 ## Note: Trackio is in Beta (DB Schema May Change)
 
@@ -158,7 +162,7 @@ Since Trackio is in beta, your feedback is welcome! Please create issues with bu
 
 ## License
 
-MIT License 
+MIT License
 
 ## Pronunciation
 

docs/source/_toctree.yml

@@ -1,3 +1,26 @@
 - sections:
   - local: index
-    title: Trackio
+    title: Trackio
+  - local: installation
+    title: Installation
+  - local: quickstart
+    title: Quickstart
+  title: Getting started
+- sections:
+  - local: track
+    title: Track
+  - local: launch
+    title: Launch the Dashboard
+  - local: deploy_embed
+    title: Deploy and Embed Dashboards
+  - local: manage
+    title: Manage Projects
+  title: How-to guides
+- sections:
+  - local: transformers_integration
+    title: Transformers Trainer
+  title: Integration
+- sections:
+  - local: api
+    title: API Reference
+  title: API

docs/source/api.md

@@ -0,0 +1,29 @@
+# API Reference
+
+## Run
+
+[[autodoc]] Run
+
+## init
+
+[[autodoc]] init
+
+## log
+
+[[autodoc]] log
+
+## finish
+
+[[autodoc]] finish
+
+## show
+
+[[autodoc]] show
+
+## import_csv
+
+[[autodoc]] import_csv
+
+## import_tf_events
+
+[[autodoc]] import_tf_events

docs/source/deploy_embed.md

@@ -0,0 +1,58 @@
+# Deploying and Embedding Dashboards
+
+## Deploying to Hugging Face Spaces
+
+When calling [`init`], by default the service will run locally and store project data on the local machine.
+
+But if you pass a `space_id` to [`init`], like:
+
+```py
+trackio.init(project="my-project", space_id="orgname/space_id")
+```
+
+or
+
+```py
+trackio.init(project="my-project", space_id="username/space_id")
+```
+
+it will use an existing or automatically deploy a new Hugging Face Space as needed. You should be logged in with the `huggingface-cli` locally and your token should have write permissions to create the Space.
+
+## Embedding a Trackio Dashboard
+
+One of the reasons we created `trackio` was to make it easy to embed live dashboards on websites, blog posts, or anywhere else you can embed a website.
+
+![image](https://github.com/user-attachments/assets/77f1424b-737b-4f04-b828-a12b2c1af4ef)
+
+If your Trackio dashboard is hosted on Spaces, you can embed it anywhere using an `<iframe>`:
+
+```html
+<iframe src="https://username-space_id.hf.space"></iframe>
+```
+
+You can also filter the dashboard to display only specific projects or metrics using query parameters. Supported parameters include:
+
+* `project` (string): Show only a specific project.
+* `metrics` (comma-separated list): Show only specific metrics, e.g., `train_loss,train_accuracy`.
+* `sidebar` (string, `"hidden"` or `"collapsed"`):
+
+  * `"hidden"` hides the sidebar completely.
+  * `"collapsed"` keeps the sidebar initially collapsed, but the user can expand it. By default, the sidebar is visible and open.
+
+You can customize your `<iframe>` using standard attributes such as `width`, `height`, and `style`. For more details, see [MDN Web Docs: `<iframe>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe). For example:
+
+```html
+<iframe 
+    src="https://trackio-documentation.hf.space/?project=my-project&metrics=train_loss,train_accuracy&sidebar=hidden" 
+    width="600" 
+    height="630" 
+    style="border:0;">
+</iframe>
+```
+
+<iframe 
+    src="https://trackio-documentation.hf.space/?project=my-project&metrics=train_loss,train_accuracy&sidebar=hidden" 
+    width="600" 
+    height="630" 
+    style="border:0;">
+</iframe>

docs/source/index.md

@@ -1 +1,22 @@
 # Trackio
+
+<p align="center">
+<img width="75%" src="https://github.com/user-attachments/assets/6d6a41e7-fbc1-43ec-bda6-15f9ff4bd25c" />
+</p>
+
+`trackio` is a lightweight, free experiment tracking Python library built on top of Hugging Face Datasets and Spaces 🤗.
+
+![Screen Recording 2025-07-28 at 5 26 32 PM](https://github.com/user-attachments/assets/f3eac49e-d8ee-4fc0-b1ca-aedfc6d6fae1)
+
+- **API compatible** with `wandb.init`, `wandb.log`, and `wandb.finish`. Drop-in replacement: just
+
+  ```python
+  import trackio as wandb
+  ```
+
+- **Local-first** design: dashboard runs locally by default. You can also host it on Spaces by specifying a `space_id`.
+- Persists logs locally (or in a private Hugging Face Dataset)
+- Visualize experiments with a Gradio dashboard locally (or on Hugging Face Spaces)
+- Everything here, including hosting on Hugging Face, is **free**!
+
+Trackio is designed to be lightweight (the core codebase is <3,000 lines of Python code), not fully-featured. It is designed in an extensible way and written entirely in Python so that developers can easily fork the repository and add functionality that they care about.