Add more doc in guide-cli

Fix problems linked to PR

crates/heat-sdk-cli/src/cli_commands/package/mod.rs

@@ -8,22 +8,17 @@ use quote::ToTokens;
 
 #[derive(Parser, Debug)]
 pub struct PackageArgs {
-    /// The Heat project ID
+    /// The Heat project path
     // todo: support project name and creating a project if it doesn't exist
     #[clap(
         short = 'p',
         long = "project",
         required = true,
-        help = "<required> The Heat project path. Ex: test/Default-Project"
+        help = "The Heat project path. Ex: test/Default-Project"
     )]
     project_path: String,
     /// The Heat API key
-    #[clap(
-        short = 'k',
-        long = "key",
-        required = true,
-        help = "<required> The Heat API key."
-    )]
+    #[clap(short = 'k', long = "key", required = true, help = "The Heat API key.")]
     key: String,
 }
 

crates/heat-sdk-cli/src/cli_commands/run/mod.rs

@@ -11,9 +11,7 @@ use crate::context::HeatCliContext;
 /// Only local training is supported at the moment.
 #[derive(Parser, Debug)]
 pub enum RunLocationType {
-    /// {training|inference} : Run a training or inference locally.
     Training(TrainingRunArgs),
-    /// todo
     Inference(InferenceRunArgs),
 }
 

crates/heat-sdk-cli/src/cli_commands/run/training.rs

@@ -17,33 +17,28 @@ use crate::{
 #[derive(Parser, Debug)]
 pub struct TrainingRunArgs {
     /// The training functions to run
-    #[clap(short = 'f', long="functions", value_delimiter = ' ', num_args = 1.., required = true, help = "<required> The training functions to run. Annotate a training function with #[heat(training)] to register it."
+    #[clap(short = 'f', long="functions", value_delimiter = ' ', num_args = 1.., required = true, help = "The training functions to run. Annotate a training function with #[heat(training)] to register it."
     )]
     functions: Vec<String>,
     /// Backend to use
-    #[clap(short = 'b', long = "backends", value_delimiter = ' ', num_args = 1.., required = true, help = "<required> Backends to use for training."
+    #[clap(short = 'b', long = "backends", value_delimiter = ' ', num_args = 1.., required = true, help = "Backends to use for training."
     )]
     backends: Vec<BackendType>,
     /// Config files paths
-    #[clap(short = 'c', long = "configs", value_delimiter = ' ', num_args = 1.., required = true, help = "<required> Config files paths."
+    #[clap(short = 'c', long = "configs", value_delimiter = ' ', num_args = 1.., required = true, help = "Config files paths."
     )]
     configs: Vec<String>,
-    /// The Heat project ID
+    /// The Heat project path
     // todo: support project name and creating a project if it doesn't exist
     #[clap(
         short = 'p',
         long = "project",
         required = true,
-        help = "<required> The Heat project ID."
+        help = "The Heat project path."
     )]
     project_path: String,
     /// The Heat API key
-    #[clap(
-        short = 'k',
-        long = "key",
-        required = true,
-        help = "<required> The Heat API key."
-    )]
+    #[clap(short = 'k', long = "key", required = true, help = "The Heat API key.")]
     key: String,
     /// Project version
     #[clap(short = 't', long = "version", help = "The project version.")]
@@ -57,7 +52,8 @@ pub(crate) fn handle_command(args: TrainingRunArgs, context: HeatCliContext) ->
     match (&args.runner, &args.project_version) {
         (Some(_), Some(_)) => remote_run(args, context),
         (None, None) => local_run(args, context),
-        _ => Err(anyhow::anyhow!("Both runner and project version must be specified for remote run and none for local run.")),
+        (Some(_), None) => Err(anyhow::anyhow!("You must provide the project version to run on the runner with --version argument")),
+        (None, Some(_)) => Err(anyhow::anyhow!("Project version is ignored when executing locally (i.e. no runner is defined with --runner argument"))
     }
 }
 
@@ -183,8 +179,7 @@ fn check_function_registered(function: &str, flags: &[Flag]) -> anyhow::Result<(
                 .collect::<Vec<String>>()
                 .join("\n");
 
-
-            Err(anyhow::anyhow!(format!("Function `{}` is registered multiple times. Please write the entire module path of the desired function:\n{}", function.custom_color(BURN_ORANGE).bold(), function_strings)))
+            Err(anyhow::anyhow!(format!("Function `{}` is registered multiple times. Please provide the fully qualified function name by writing the entire module path of the function:\n{}", function.custom_color(BURN_ORANGE).bold(), function_strings)))
         }
     }
 }

crates/heat-sdk-cli/src/commands/mod.rs

@@ -23,17 +23,10 @@ pub enum RunParams {
 /// Contains the data necessary to build an experiment.
 #[derive(Debug)]
 pub struct BuildCommand {
-    // pub command: Command,
     pub run_id: String,
     pub backend: BackendType,
-    // pub dest_exe_name: String
 }
 
-// #[derive(Debug)]
-// pub enum BuildParams {
-//     Training {}
-// }
-
 /// Execute the build and run commands for an experiment.
 pub(crate) fn execute_experiment_command(
     build_command: BuildCommand,

crates/heat-sdk-cli/src/generation/crate_gen/mod.rs

@@ -225,7 +225,7 @@ fn generate_clap_cli() -> proc_macro2::TokenStream {
                 clap::Arg::new("project")
                     .short('p')
                     .long("project")
-                    .help("The project ID")
+                    .help("The project path")
                     .required(true),
                 clap::Arg::new("key")
                     .short('k')

crates/heat-sdk/src/client.rs

@@ -48,7 +48,7 @@ pub struct HeatClientConfig {
     pub num_retries: u8,
     /// The interval to wait between retries in seconds.
     pub retry_interval: u64,
-    /// The project ID to create the experiment in.
+    /// The project path to create the experiment in.
     pub project_path: ProjectPath,
 }
 

examples/guide-cli/README.md

@@ -1,16 +1,61 @@
-## To run guide-cli using the CLI, use a command of this format:
+# Running a project with the Heat SDK CLI:
+### [Running a training locally](#run-local-training)
+### [Running a training remotely](#run-remote-training)
+### [Command arguments](#command-arguments)
+### [Setting up a runner](#setting-up-a-runner)
 
-### Run local training:
+<br />
+<br />
+<br />
+
+## Run local training:
+
+You can use the `run` command to run a training locally and upload training data automatically to `Heat`.\
 
 ```sh
-cargo run --bin guide-cli -- run training --functions training --backends wgpu --configs train_configs/config.json --key <API_KEY> --project <PROJECT_ID>
+cargo run --bin guide-cli -- run training --functions <TRAINING_FUNCTION> --backends <BURN_BACKEND> --configs <CONFIG_FILE_PATH> --key <HEAT_API_KEY> --project <PROJECT_PATH>
 ```
 
-### Run remote training:
+## Run remote training:
+
+First, you need to upload the project code with the `package` command.\
+This command takes your rust project and packages it into a `.crate` file which is then uploaded to `Heat`.\
+The `package` command will tell you which version you just uploaded.\
+To use this version in the future, you will need to specify it when running the project (either the full hash or the short version).
 
-PROJECT_VERSION is the commit hash of the project version to run, it is given when running the package command
+Then, you can run the project with the `run` command and the `--runner` flag to run it remotely on that runner group.
+If you have not set up a runner yet, please follow the [**Setting up a runner**](#setting-up-a-runner) section of this file.
+You can then use the project version you uploaded with the `package` command to run the project on the runner group you set up.
+
+```sh
+cargo run --bin guide-cli -- package --key <HEAT_API_KEY> --project <PROJECT_PATH>
+```
 
 ```sh
-cargo run --bin guide-cli -- package --key <API_KEY> --project <PROJECT_ID>
-cargo run --bin guide-cli -- run training --functions training --backends wgpu --configs train_configs/config.json --key <API_KEY> --project <PROJECT_ID> --runner <RUNNER_GROUP_NAME> --version <PROJECT_VERSION>
-```
+cargo run --bin guide-cli -- run training --functions <TRAINING_FUNCTION> --backends <BURN_BACKEND> --configs <CONFIG_FILE_PATH> --key <HEAT_API_KEY> --project <PROJECT_PATH> --runner <RUNNER_GROUP_NAME> --version <PROJECT_VERSION>
+```
+
+## Command arguments:
+TRAINING_FUNCTION: A registered training function, or space separated list of functions, in the project. To register a function, annotate it with `#[heat(training)]`.\
+BURN_BACKEND: A backend, or multiple backends, supported by Burn on which you want to run the training. See [the heat-sdk-cli file](https://github.com/tracel-ai/tracel/blob/main/crates/heat-sdk-cli/src/generation/crate_gen/backend.rs) for a list of supported backends.\
+CONFIG_FILE_PATH: Path(s) to the configuration file(s) for the training (relative to the crate root).\
+HEAT_API_KEY: Your Heat API key. To create an API key, go to your settings page on the [Heat](https://heat.tracel.ai/) website.\
+PROJECT_PATH: The identifier for the project you want to run. A project path is composed of your Heat username and the project name, separated by a slash. Note that the name is case-insensitive. Ex: `test/Default-Project.\
+RUNNER_GROUP_NAME: The name of the runner group you want to run the project on. See [**Setting up a runner**](#setting-up-a-runner) for more information.\
+PROJECT_VERSION: The commit hash of the project version to run. This is given when running the package command. You can also use the commit hash of a specific commit you have uploaded to Heat to run that version. You can also use the short version of the hash.
+
+## Setting up a runner:
+Two steps are required to set up a runner:
+
+1. Create and register a runner on the `Heat` website.
+    - Go to the [Heat](https://heat.tracel.ai/) website and log in.
+    - Go to your `Runners` page.
+    - Click on the "New runner" button and follow the instructions.
+    - (Optional) On the last page, you will have the opportunity to directly assign the runner to a project by creating a runner group with same name as the runner itself in the selected project. You can also do it manually in the next step if you want more options.
+
+2. Add the runner to a runner group in the project you want to run.
+    - Go to the project page.
+    - Go to the `Jobs` page.
+    - Go to the `Runner Groups` tab.
+    - If you already have a runner group and want to add the newly created runner to it, click on the runner group and add it by selecting the runner and the API key it should use from the dropdowns and then clicking `Assign`.
+    - If you don't have a runner group yet (or do not want to add it to an existing group), click on the `Create group` button and choose a name for it. Then add the runner to the group as described above.

examples/guide-cli/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 //
 // Note: If you are following the Burn Book guide this file can be ignored.
 //

examples/guide/src/main.rs

@@ -47,7 +47,7 @@ struct Args {
     #[arg(short, long, default_value = "http://localhost:9001")]
     url: String,
 
-    /// The project ID in which the experiment will be created.
+    /// The project path in which the experiment will be created.
     #[arg(short, long)]
     project: String,
 }