Skip to content

Commit

Permalink
Improve beginner experience (#645)
Browse files Browse the repository at this point in the history
# Objective

Hi! This PR proposes several changes to the installation process,
`README.md`, and examples to make it easier for beginners to get started
with Dora.

## Installation

- The `install.sh` script for Linux and macOS now automatically detects
the user's terminal and asks if they want to add `.dora/bin` to their
PATH automatically.

- A new `install.ps1` script does the same for Windows. The following
command (note: it doesn't work yet because this PR hasn't been merged
into the main branch, so the path needs to be adapted) works regardless
of whether the user is in CMD, bash, or PowerShell (this helps avoid
potential errors):
```bash
powershell -c "irm https://raw.githubusercontent.com/dora-rs/dora/main/install.ps1 | iex"
```

=> I believe having a standalone installation script will help convince
more beginners to use Dora (especially among students/teachers). Using
`crates.io` requires several steps, particularly on Windows:
**installing Rustup**, simultaneously **installing MSVC**, and then
installing `dora-cli`. For many who are not Rust developers, this can
involve too many steps (especially regarding MSVC, since the Visual
Installer interface is not very intuitive, and beginners might not know
what to install).

## README.md

I was inspired by existing GitHub projects to propose a clearer
`README.md` that quickly highlights the important steps of the project:
**Highlights**, **Installation**, and **Documentation/Getting Started**.

## Examples

I haven't worked on this part yet, but I think it's necessary to rework
our `examples` folder. I find it easy to get lost in it as it currently
feels more like a `tests` directory than examples meant to guide a user.

What would be helpful is:
- Creating more explicit examples like `rust-talker-listener`,
`python-video-capture`, `rust-speech-to-text`, `python-ros2-bridge`,
`multiple-machine-talker-listener`, etc., instead of just
`c++-dataflow`, `python-dataflow`, etc.

- Automatically integrating all our examples into the `CI`.

- For the `python` examples, to facilitate execution with `run.rs`
scripts, it might be worth considering using `uv`
(<https://github.com/astral-sh/uv>), as they offer a crate that allows
managing an entire `python` installation, `venv`, `dependencies` from
Rust. This might be simpler than having to find a Python binary, install
everything, etc.
  • Loading branch information
Hennzau authored Sep 9, 2024
2 parents e3ec7fb + 52df62c commit 28ebac9
Show file tree
Hide file tree
Showing 13 changed files with 1,897 additions and 153 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -168,4 +168,7 @@ cython_debug/
# log output file
out/

# MacOS DS_Store
.DS_Store

~*
274 changes: 133 additions & 141 deletions README.md

Large diffs are not rendered by default.

221 changes: 221 additions & 0 deletions docs/src/Dora-RS.drawio

Large diffs are not rendered by default.

Loading

0 comments on commit 28ebac9

Please sign in to comment.