Merge branch 'slides/209-use_rust_role' into 'master'

Use rust role for syntax highlighting

Closes #209

See merge request feng/training/material!284

courses/comprehensive_rust_training/020_hello_world/01_what_is_rust.rst

@@ -11,7 +11,7 @@ Rust is a new programming language which had its `1.0 release in
 
 -  Rust is a statically compiled language in a similar role as C++
 
-   -  ``rustc`` uses LLVM as its backend.
+   -  :rust:`rustc` uses LLVM as its backend.
 
 -  Rust supports many `platforms and
    architectures <https://doc.rust-lang.org/nightly/rustc/platform-support.html>`__:
@@ -27,8 +27,6 @@ Rust is a new programming language which had its `1.0 release in
    -  desktops,
    -  servers.
 
-.. raw:: html
-
 ---------
 Details
 ---------
@@ -41,6 +39,3 @@ Rust fits in the same area as C++:
    microcontrollers.
 -  Has no runtime or garbage collection.
 -  Focuses on reliability and safety without sacrificing performance.
-
-.. raw:: html
-

courses/comprehensive_rust_training/020_hello_world/02_benefits.rst

@@ -14,7 +14,7 @@ Some unique selling points of Rust:
    -  No uninitialized variables.
    -  No double-frees.
    -  No use-after-free.
-   -  No ``NULL`` pointers.
+   -  No :rust:`NULL` pointers.
    -  No forgotten locked mutexes.
    -  No data races between threads.
    -  No iterator invalidation.
@@ -37,8 +37,6 @@ Some unique selling points of Rust:
    -  Built-in support for testing.
    -  Excellent Language Server Protocol support.
 
-.. raw:: html
-
 ---------
 Details
 ---------
@@ -60,6 +58,3 @@ Depending on the answer you can highlight different features of Rust:
    language feeling. In addition you get fast and predictable
    performance like C and C++ (no garbage collector) as well as access
    to low-level hardware (should you need it).
-
-.. raw:: html
-

courses/comprehensive_rust_training/020_hello_world/03_playground.rst

@@ -11,7 +11,7 @@ way to run short Rust programs, and is the basis for the examples and
 exercises in this course. Try running the "hello-world" program it
 starts with. It comes with a few handy features:
 
--  Under "Tools", use the ``rustfmt`` option to format your code in the
+-  Under "Tools", use the :rust:`rustfmt` option to format your code in the
    "standard" way.
 
 -  Rust has two main "profiles" for generating code: Debug (extra
@@ -21,8 +21,6 @@ starts with. It comes with a few handy features:
 -  If you're interested, use "ASM" under "..." to see the generated
    assembly code.
 
-.. raw:: html
-
 ---------
 Details
 ---------
@@ -32,6 +30,3 @@ playground and experiment a little. Encourage them to keep the tab open
 and try things out during the rest of the course. This is particularly
 helpful for advanced students who want to know more about Rust's
 optimizations or generated assembly.
-
-.. raw:: html
-

courses/comprehensive_rust_training/030_types_and_values/01_hello_world.rst

@@ -9,22 +9,20 @@ Hello, World
 Let us jump into the simplest possible Rust program, a classic Hello
 World program:
 
-.. code:: rust,editable
+.. code:: rust
 
    fn main() {
        println!("Hello World!");
    }
 
 What you see:
 
--  Functions are introduced with ``fn``.
+-  Functions are introduced with :rust:`fn`.
 -  Blocks are delimited by curly braces like in C and C++.
--  The ``main`` function is the entry point of the program.
--  Rust has hygienic macros, ``println!`` is an example of this.
+-  The :rust:`main` function is the entry point of the program.
+-  Rust has hygienic macros, :rust:`println!` is an example of this.
 -  Rust strings are UTF-8 encoded and can contain any Unicode character.
 
-.. raw:: html
-
 ---------
 Details
 ---------
@@ -56,6 +54,3 @@ Key points:
    while it is not a functional language, it includes a range of
    `functional
    concepts <https://doc.rust-lang.org/book/ch13-00-functional-features.html>`__.
-
-.. raw:: html
-

courses/comprehensive_rust_training/030_types_and_values/02_variables.rst

@@ -7,9 +7,9 @@ Variables
 -----------
 
 Rust provides type safety via static typing. Variable bindings are made
-with ``let``:
+with :rust:`let`:
 
-.. code:: rust,editable,warnunused
+.. code:: rust
 
    fn main() {
        let x: i32 = 10;
@@ -18,23 +18,18 @@ with ``let``:
        // println!("x: {x}");
    }
 
-.. raw:: html
-
 ---------
 Details
 ---------
 
--  Uncomment the ``x = 20`` to demonstrate that variables are immutable
-   by default. Add the ``mut`` keyword to allow changes.
+-  Uncomment the :rust:`x = 20` to demonstrate that variables are immutable
+   by default. Add the :rust:`mut` keyword to allow changes.
 
 -  Warnings are enabled for this slide, such as for unused variables or
-   unnecessary ``mut``. These are omitted in most slides to avoid
+   unnecessary :rust:`mut`. These are omitted in most slides to avoid
    distracting warnings. Try removing the mutation but leaving the
-   ``mut`` keyword in place.
+   :rust:`mut` keyword in place.
 
--  The ``i32`` here is the type of the variable. This must be known at
+-  The :rust:`i32` here is the type of the variable. This must be known at
    compile time, but type inference (covered later) allows the
    programmer to omit it in many cases.
-
-.. raw:: html
-

courses/comprehensive_rust_training/030_types_and_values/03_values.rst

@@ -38,12 +38,10 @@ each type.
 
 The types have widths as follows:
 
--  ``iN``, ``uN``, and ``fN`` are *N* bits wide,
--  ``isize`` and ``usize`` are the width of a pointer,
--  ``char`` is 32 bits wide,
--  ``bool`` is 8 bits wide.
-
-.. raw:: html
+-  :rust:`iN`, :rust:`uN`, and :rust:`fN` are *N* bits wide,
+-  :rust:`isize` and :rust:`usize` are the width of a pointer,
+-  :rust:`char` is 32 bits wide,
+-  :rust:`bool` is 8 bits wide.
 
 ---------
 Details
@@ -52,8 +50,5 @@ Details
 There are a few syntaxes which are not shown above:
 
 -  All underscores in numbers can be left out, they are for legibility
-   only. So ``1_000`` can be written as ``1000`` (or ``10_00``), and
-   ``123_i64`` can be written as ``123i64``.
-
-.. raw:: html
-
+   only. So :rust:`1_000` can be written as :rust:`1000` (or :rust:`10_00`), and
+   :rust:`123_i64` can be written as :rust:`123i64`.

courses/comprehensive_rust_training/030_types_and_values/04_arithmetic.rst

@@ -6,7 +6,7 @@ Arithmetic
 Arithmetic
 ------------
 
-.. code:: rust,editable
+.. code:: rust
 
    fn interproduct(a: i32, b: i32, c: i32) -> i32 {
        return a * b + b * c + c * a;
@@ -16,13 +16,11 @@ Arithmetic
        println!("result: {}", interproduct(120, 100, 248));
    }
 
-.. raw:: html
-
 ---------
 Details
 ---------
 
-This is the first time we've seen a function other than ``main``, but
+This is the first time we've seen a function other than :rust:`main`, but
 the meaning should be clear: it takes three integers, and returns an
 integer. Functions will be covered in more detail later.
 
@@ -32,14 +30,11 @@ What about integer overflow? In C and C++ overflow of *signed* integers
 is actually undefined, and might do unknown things at runtime. In Rust,
 it's defined.
 
-Change the ``i32``\ 's to ``i16`` to see an integer overflow, which
+Change the :rust:`i32` to :rust:`i16` to see an integer overflow, which
 panics (checked) in a debug build and wraps in a release build. There
 are other options, such as overflowing, saturating, and carrying. These
 are accessed with method syntax, e.g.,
-``(a * b).saturating_add(b * c).saturating_add(c * a)``.
+:rust:`(a * b).saturating_add(b * c).saturating_add(c * a)`.
 
 In fact, the compiler will detect overflow of constant expressions,
 which is why the example requires a separate function.
-
-.. raw:: html
-

courses/comprehensive_rust_training/030_types_and_values/05_inference.rst

@@ -8,11 +8,7 @@ Type Inference
 
 Rust will look at how the variable is *used* to determine the type:
 
-.. raw:: html
-
-   <!-- mdbook-xgettext: skip -->
-
-.. code:: rust,editable
+.. code:: rust
 
    fn takes_u32(x: u32) {
        println!("u32: {x}");
@@ -31,8 +27,6 @@ Rust will look at how the variable is *used* to determine the type:
        // takes_u32(y);
    }
 
-.. raw:: html
-
 ---------
 Details
 ---------
@@ -47,17 +41,14 @@ declaration of a type. The compiler does the job for us and helps us
 write more concise code.
 
 When nothing constrains the type of an integer literal, Rust defaults to
-``i32``. This sometimes appears as ``{integer}`` in error messages.
-Similarly, floating-point literals default to ``f64``.
+:rust:`i32`. This sometimes appears as :rust:`{integer}` in error messages.
+Similarly, floating-point literals default to :rust:`f64`.
 
-.. code:: rust,compile_fail
+.. code:: rust
 
    fn main() {
        let x = 3.14;
        let y = 20;
        assert_eq!(x, y);
        // ERROR: no implementation for `{float} == {integer}`
    }
-
-.. raw:: html
-

courses/comprehensive_rust_training/030_types_and_values/06_exercise.rst

@@ -6,14 +6,14 @@ Exercise: Fibonacci
 Exercise: Fibonacci
 ---------------------
 
-The Fibonacci sequence begins with ``[0,1]``. For n>1, the n'th
+The Fibonacci sequence begins with :rust:`[0,1]`. For n>1, the n'th
 Fibonacci number is calculated recursively as the sum of the n-1'th and
 n-2'th Fibonacci numbers.
 
-Write a function ``fib(n)`` that calculates the n'th Fibonacci number.
+Write a function :rust:`fib(n)` that calculates the n'th Fibonacci number.
 When will this function panic?
 
-.. code:: rust,editable,should_panic
+::
 
    {{#include exercise.rs:fib}}
        if n < 2 {

courses/comprehensive_rust_training/040_control_flow_basics/01_if.rst

@@ -1,16 +1,16 @@
 ====================
-``if`` expressions
+"if" expressions
 ====================
 
 --------------------
-``if`` expressions
+"if" expressions
 --------------------
 
 You use
 :url:`if expressions <https://doc.rust-lang.org/reference/expressions/if-expr.html#if-expressions>`
-exactly like ``if`` statements in other languages:
+exactly like :rust:`if` statements in other languages:
 
-.. code:: rust,editable
+.. code:: rust
 
    fn main() {
        let x = 10;
@@ -23,31 +23,26 @@ exactly like ``if`` statements in other languages:
        }
    }
 
-In addition, you can use ``if`` as an expression. The last expression of
-each block becomes the value of the ``if`` expression:
+In addition, you can use :rust:`if` as an expression. The last expression of
+each block becomes the value of the :rust:`if` expression:
 
-.. code:: rust,editable
+.. code:: rust
 
    fn main() {
        let x = 10;
        let size = if x < 20 { "small" } else { "large" };
        println!("number size: {}", size);
    }
 
-.. raw:: html
-
 ---------
 Details
 ---------
 
-Because ``if`` is an expression and must have a particular type, both of
+Because :rust:`if` is an expression and must have a particular type, both of
 its branch blocks must have the same type. Show what happens if you add
-``;`` after ``"small"`` in the second example.
-
-An ``if`` expression should be used in the same way as the other
-expressions. For example, when it is used in a ``let`` statement, the
-statement must be terminated with a ``;`` as well. Remove the ``;``
-before ``println!`` to see the compiler error.
-
-.. raw:: html
+:rust:`;` after :rust:`"small"` in the second example.
 
+An :rust:`if` expression should be used in the same way as the other
+expressions. For example, when it is used in a :rust:`let` statement, the
+statement must be terminated with a :rust:`;` as well. Remove the :rust:`;`
+before :rust:`println!` to see the compiler error.