Skip to content

Commit f387f4c

Browse files
mo8itmo8it
committed
Add setup and usage pages
1 parent b30973a commit f387f4c

File tree

5 files changed

+150
-135
lines changed

5 files changed

+150
-135
lines changed

‎website/content/_index.md‎

Lines changed: 8 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -3,137 +3,19 @@
33

44
Small exercises to get you used to reading and writing [Rust](https://www.rust-lang.org) code - _Recommended in parallel to reading [the official Rust book](https://doc.rust-lang.org/book) 📚️_
55

6-
<!-- toc -->
6+
<script src="https://asciinema.org/a/719805.js" id="asciicast-719805" async="true"></script>
77

8-
## Getting Started
9-
10-
### Installing Rust
11-
12-
Before installing Rustlings, you need to have the **latest version of Rust** installed.
13-
Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions on installing Rust.
14-
This will also install _Cargo_, Rust's package/project manager.
15-
16-
> 🐧 If you are on Linux, make sure you have installed `gcc` (for a linker).
17-
>
18-
> Deb: `sudo apt install gcc`
19-
>
20-
> Dnf: `sudo dnf install gcc`
21-
22-
> 🍎 If you are on MacOS, make sure you have installed Xcode and its developer tools by running `xcode-select --install`.
23-
24-
### Installing Rustlings
25-
26-
The following command will download and compile Rustlings:
8+
## Quick start
279

2810
```bash
11+
# Installation
2912
cargo install rustlings
30-
```
31-
32-
<details>
33-
<summary><strong>If the installation fails…</strong> (<em>click to expand</em>)</summary>
34-
35-
- Make sure you have the latest Rust version by running `rustup update`
36-
- Try adding the `--locked` flag: `cargo install rustlings --locked`
37-
- Otherwise, please [report the issue](https://github.com/rust-lang/rustlings/issues/new)
38-
39-
</details>
40-
41-
### Initialization
42-
43-
After installing Rustlings, run the following command to initialize the `rustlings/` directory:
44-
45-
```bash
13+
# Initialization
4614
rustlings init
47-
```
48-
49-
<details>
50-
<summary><strong>If the command <code>rustlings</code> can't be found…</strong> (<em>click to expand</em>)</summary>
51-
52-
You are probably using Linux and installed Rust using your package manager.
53-
54-
Cargo installs binaries to the directory `~/.cargo/bin`.
55-
Sadly, package managers often don't add `~/.cargo/bin` to your `PATH` environment variable.
56-
57-
The solution is to …
58-
59-
- either add `~/.cargo/bin` manually to `PATH`
60-
- or to uninstall Rust from the package manager and install it using the official way with `rustup`: https://www.rust-lang.org/tools/install
61-
62-
</details>
63-
64-
Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises:
65-
66-
```bash
67-
cd rustlings/
15+
# Moving into new directory
16+
cd rustlings
17+
# Starting Rustlings
6818
rustlings
6919
```
7020

71-
## Working environment
72-
73-
### Editor
74-
75-
Our general recommendation is [VS Code](https://code.visualstudio.com/) with the [rust-analyzer plugin](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
76-
But any editor that supports [rust-analyzer](https://rust-analyzer.github.io/) should be enough for working on the exercises.
77-
78-
### Terminal
79-
80-
While working with Rustlings, please use a modern terminal for the best user experience.
81-
The default terminal on Linux and Mac should be sufficient.
82-
On Windows, we recommend the [Windows Terminal](https://aka.ms/terminal).
83-
84-
## Doing exercises
85-
86-
The exercises are sorted by topic and can be found in the subdirectory `exercises/<topic>`.
87-
For every topic, there is an additional `README.md` file with some resources to get you started on the topic.
88-
We highly recommend that you have a look at them before you start 📚️
89-
90-
Most exercises contain an error that keeps them from compiling, and it's up to you to fix it!
91-
Some exercises contain tests that need to pass for the exercise to be done ✅
92-
93-
Search for `TODO` and `todo!()` to find out what you need to change.
94-
Ask for hints by entering `h` in the _watch mode_ 💡
95-
96-
### Watch Mode
97-
98-
After the [initialization](#initialization), Rustlings can be launched by simply running the command `rustlings`.
99-
100-
This will start the _watch mode_ which walks you through the exercises in a predefined order (what we think is best for newcomers).
101-
It will rerun the current exercise automatically every time you change the exercise's file in the `exercises/` directory.
102-
103-
<details>
104-
<summary><strong>If detecting file changes in the <code>exercises/</code> directory fails…</strong> (<em>click to expand</em>)</summary>
105-
106-
> You can add the **`--manual-run`** flag (`rustlings --manual-run`) to manually rerun the current exercise by entering `r` in the watch mode.
107-
>
108-
> Please [report the issue](https://github.com/rust-lang/rustlings/issues/new) with some information about your operating system and whether you run Rustlings in a container or virtual machine (e.g. WSL).
109-
110-
</details>
111-
112-
### Exercise List
113-
114-
In the [watch mode](#watch-mode) (after launching `rustlings`), you can enter `l` to open the interactive exercise list.
115-
116-
The list allows you to…
117-
118-
- See the status of all exercises (done or pending)
119-
- `c`: Continue at another exercise (temporarily skip some exercises or go back to a previous one)
120-
- `r`: Reset status and file of the selected exercise (you need to _reload/reopen_ its file in your editor afterwards)
121-
122-
See the footer of the list for all possible keys.
123-
124-
## Questions?
125-
126-
If you need any help while doing the exercises and the builtin-hints aren't helpful, feel free to ask in the [_Q&A_ category of the discussions](https://github.com/rust-lang/rustlings/discussions/categories/q-a?discussions_q=) if your question wasn't asked yet 💡
127-
128-
## Continuing On
129-
130-
Once you've completed Rustlings, put your new knowledge to good use!
131-
Continue practicing your Rust skills by building your own projects, contributing to Rustlings, or finding other open-source projects to contribute to.
132-
133-
## Uninstalling Rustlings
134-
135-
If you want to remove Rustlings from your system, run the following command:
136-
137-
```bash
138-
cargo uninstall rustlings
139-
```
21+
Visit the [**setup**](@/setup/index.md) page for more details 🧰

‎website/content/setup/index.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
+++
2+
title = "Setup"
3+
+++
4+
5+
<!-- toc -->
6+
7+
## Installing Rust
8+
9+
Before installing Rustlings, you need to have the **latest version of Rust** installed.
10+
Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions on installing Rust.
11+
This will also install _Cargo_, Rust's package/project manager.
12+
13+
> 🐧 If you are on Linux, make sure you have installed `gcc` (for a linker).
14+
>
15+
> Deb: `sudo apt install gcc`
16+
>
17+
> Dnf: `sudo dnf install gcc`
18+
19+
> 🍎 If you are on MacOS, make sure you have installed Xcode and its developer tools by running `xcode-select --install`.
20+
21+
## Installing Rustlings
22+
23+
The following command will download and compile Rustlings:
24+
25+
```bash
26+
cargo install rustlings
27+
```
28+
29+
<details>
30+
<summary><strong>If the installation fails…</strong> (<em>click to expand</em>)</summary>
31+
32+
> - Make sure you have the latest Rust version by running `rustup update`
33+
> - Try adding the `--locked` flag: `cargo install rustlings --locked`
34+
> - Otherwise, please [report the issue](https://github.com/rust-lang/rustlings/issues/new)
35+
36+
</details>
37+
38+
## Initialization
39+
40+
After installing Rustlings, run the following command to initialize the `rustlings/` directory:
41+
42+
```bash
43+
rustlings init
44+
```
45+
46+
<details>
47+
<summary><strong>If the command <code>rustlings</code> can't be found…</strong> (<em>click to expand</em>)</summary>
48+
49+
> You are probably using Linux and installed Rust using your package manager.
50+
>
51+
> Cargo installs binaries to the directory `~/.cargo/bin`.
52+
> Sadly, package managers often don't add `~/.cargo/bin` to your `PATH` environment variable.
53+
>
54+
> - Either add `~/.cargo/bin` manually to `PATH`
55+
> - Or uninstall Rust from the package manager and [install it using the official way with `rustup`](https://www.rust-lang.org/tools/install)
56+
57+
</details>
58+
59+
Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises:
60+
61+
```bash
62+
cd rustlings/
63+
rustlings
64+
```
65+
66+
## Working environment
67+
68+
### Editor
69+
70+
Our general recommendation is [VS Code](https://code.visualstudio.com/) with the [rust-analyzer plugin](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
71+
But any editor that supports [rust-analyzer](https://rust-analyzer.github.io/) should be enough for working on the exercises.
72+
73+
### Terminal
74+
75+
While working with Rustlings, please use a modern terminal for the best user experience.
76+
The default terminal on Linux and Mac should be sufficient.
77+
On Windows, we recommend the [Windows Terminal](https://aka.ms/terminal).

‎website/content/usage/index.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
+++
2+
title = "Usage"
3+
+++
4+
5+
<!-- toc -->
6+
7+
## Doing exercises
8+
9+
The exercises are sorted by topic and can be found in the subdirectory `exercises/<topic>`.
10+
For every topic, there is an additional `README.md` file with some resources to get you started on the topic.
11+
We highly recommend that you have a look at them before you start 📚️
12+
13+
Most exercises contain an error that keeps them from compiling, and it's up to you to fix it!
14+
Some exercises contain tests that need to pass for the exercise to be done ✅
15+
16+
Search for `TODO` and `todo!()` to find out what you need to change.
17+
Ask for hints by entering `h` in the _watch mode_ 💡
18+
19+
### Watch Mode
20+
21+
After the [initialization](@/setup/index.md#initialization), Rustlings can be launched by simply running the command `rustlings`.
22+
23+
This will start the _watch mode_ which walks you through the exercises in a predefined order (what we think is best for newcomers).
24+
It will rerun the current exercise automatically every time you change the exercise's file in the `exercises/` directory.
25+
26+
<details>
27+
<summary><strong>If detecting file changes in the <code>exercises/</code> directory fails…</strong> (<em>click to expand</em>)</summary>
28+
29+
> You can add the **`--manual-run`** flag (`rustlings --manual-run`) to manually rerun the current exercise by entering `r` in the watch mode.
30+
>
31+
> Please [report the issue](https://github.com/rust-lang/rustlings/issues/new) with some information about your operating system and whether you run Rustlings in a container or virtual machine (e.g. WSL).
32+
33+
</details>
34+
35+
### Exercise List
36+
37+
In the [watch mode](#watch-mode) (after launching `rustlings`), you can enter `l` to open the interactive exercise list.
38+
39+
The list allows you to…
40+
41+
- See the status of all exercises (done or pending)
42+
- `c`: Continue at another exercise (temporarily skip some exercises or go back to a previous one)
43+
- `r`: Reset status and file of the selected exercise (you need to _reload/reopen_ its file in your editor afterwards)
44+
45+
See the footer of the list for all possible keys.
46+
47+
## Questions?
48+
49+
If you need any help while doing the exercises and the builtin-hints aren't helpful, feel free to ask in the [_Q&A_ category of the discussions](https://github.com/rust-lang/rustlings/discussions/categories/q-a?discussions_q=) if your question wasn't asked yet 💡
50+
51+
## Continuing On
52+
53+
Once you've completed Rustlings, put your new knowledge to good use!
54+
Continue practicing your Rust skills by building your own projects, contributing to Rustlings, or finding other open-source projects to contribute to.
55+
56+
## Uninstalling Rustlings
57+
58+
If you want to remove Rustlings from your system, run the following command:
59+
60+
```bash
61+
cargo uninstall rustlings
62+
```

‎website/templates/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,6 @@
66
<div class="m-3">
77
<h1>Rustlings</h1>
88

9-
{{ section.content | replace(from="<!-- toc -->", to=macros::toc() ) | safe }}
9+
{{ section.content | safe }}
1010
</div>
1111
{% endblock %}

‎website/templates/macros.html‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,9 @@
11
{% macro toc() %}
2-
{%- if page.toc -%}
3-
{% set_global toc = page.toc %}
4-
{%- else -%}
5-
{% set_global toc = section.toc %}
6-
{%- endif -%}
7-
8-
{% if toc %}
2+
{% if page.toc %}
93
<div class="px-4 py-0.5 my-3 border-s-4 rounded-xl border-double">
104
<nav>
115
<ul class="ml-0 list-none">
12-
{% for parent in toc %}
6+
{% for parent in page.toc %}
137
{% if parent.level == 2 %}
148
<li>
159
{#- -#}

0 commit comments

Comments
 (0)