Skip to content

New way of dealing with URL's #498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Playground
Playground
------------

The `Rust Playground <https://play.rust-lang.org/>`__ provides an easy
The :url:`Rust Playground <https://play.rust-lang.org/>` provides an easy
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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Key points:

- Rust uses macros for situations where you want to have a variable
number of arguments (no function
`overloading <../control-flow-basics/functions.md>`__).
:url:`overloading <../control-flow-basics/functions.md>`).

- Macros being 'hygienic' means they don't accidentally capture
identifiers from the scope they are used in. Rust macros are actually
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
--------------------

You use
`if expressions <https://doc.rust-lang.org/reference/expressions/if-expr.html#if-expressions>`__
:url:`if expressions <https://doc.rust-lang.org/reference/expressions/if-expr.html#if-expressions>`
exactly like ``if`` statements in other languages:

.. code:: rust,editable
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ There are three looping keywords in Rust: ``while``, ``loop``, and
-----------

The
`while keyword <https://doc.rust-lang.org/reference/expressions/loop-expr.html#predicate-loops>`__
:url:`while keyword <https://doc.rust-lang.org/reference/expressions/loop-expr.html#predicate-loops>`
works much like in other languages, executing the loop body as long as
the condition is true.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@
----------------------------

If you want to immediately start the next iteration use
`continue <https://doc.rust-lang.org/reference/expressions/loop-expr.html#continue-expressions>`__.
:url:`continue <https://doc.rust-lang.org/reference/expressions/loop-expr.html#continue-expressions>`.

If you want to exit any kind of loop early, use
`break <https://doc.rust-lang.org/reference/expressions/loop-expr.html#break-expressions>`__.
:url:`break <https://doc.rust-lang.org/reference/expressions/loop-expr.html#break-expressions>`.
With ``loop``, this can take an optional expression that becomes the
value of the ``loop`` expression.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ end. The Rust standard library includes an assortment of useful macros.

- ``println!(format, ..)`` prints a line to standard output, applying
formatting described in
`std::fmt <https://doc.rust-lang.org/std/fmt/index.html>`__.
:url:`std::fmt <https://doc.rust-lang.org/std/fmt/index.html>`.
- ``format!(format, ..)`` works just like ``println!`` but returns the
result as a string.
- ``dbg!(expression)`` logs the value of the expression and returns it.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Exercise: Collatz Sequence
----------------------------

The
`Collatz Sequence <https://en.wikipedia.org/wiki/Collatz_conjecture>`__ is
:url:`Collatz Sequence <https://en.wikipedia.org/wiki/Collatz_conjecture>` is
defined as follows, for an arbitrary n1 greater than zero:

- If *ni* is 1, then the sequence terminates at *ni*.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ Details
- Operator overloading is discussed on Day 3 (generics).

- The example is a subtle reference to the
`Mars Climate Orbiter <https://en.wikipedia.org/wiki/Mars_Climate_Orbiter>`__
:url:`Mars Climate Orbiter <https://en.wikipedia.org/wiki/Mars_Climate_Orbiter>`
failure.

.. raw:: html
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ Rust has several optimizations it can employ to make enums take up less
space.

- Null pointer optimization: For
`some types <https://doc.rust-lang.org/std/option/#representation>`__, Rust
:url:`some types <https://doc.rust-lang.org/std/option/#representation>`, Rust
guarantees that ``size_of::<T>()`` equals ``size_of::<Option<T>>()``.

Example code if you want to show how the bitwise representation *may*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ interchangeably.
Details
---------

- A `newtype <tuple-structs.html>`__ is often a better alternative
- A :url:`newtype <tuple-structs.html>` is often a better alternative
since it creates a distinct type. Prefer
``struct InventoryCount(usize)`` to ``type InventoryCount = usize``.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ wherever they are used:
}

According to the
`Rust RFC Book <https://rust-lang.github.io/rfcs/0246-const-vs-static.html>`__
:url:`Rust RFC Book <https://rust-lang.github.io/rfcs/0246-const-vs-static.html>`
these are inlined upon use.

Only functions marked ``const`` can be called at compile time to
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ and therefore will not move:
}

As noted in the
`Rust RFC Book <https://rust-lang.github.io/rfcs/0246-const-vs-static.html>`__,
:url:`Rust RFC Book <https://rust-lang.github.io/rfcs/0246-const-vs-static.html>`,
these are not inlined upon use and have an actual associated memory
location. This is useful for unsafe and embedded code, and the variable
lives through the entirety of the program execution. When a
Expand All @@ -45,7 +45,7 @@ More to Explore

Because ``static`` variables are accessible from any thread, they must
be ``Sync``. Interior mutability is possible through a
`Mutex <https://doc.rust-lang.org/std/sync/struct.Mutex.html>`__,
:url:`Mutex <https://doc.rust-lang.org/std/sync/struct.Mutex.html>`,
atomic or similar.

It is common to use ``OnceLock`` in a static as a way to support
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ languages. They are used for pattern matching:
------------------------

The
`if let expression <https://doc.rust-lang.org/reference/expressions/if-expr.html#if-let-expressions>`__
:url:`if let expression <https://doc.rust-lang.org/reference/expressions/if-expr.html#if-let-expressions>`
lets you execute different code depending on whether a value matches a
pattern:

Expand Down Expand Up @@ -52,7 +52,7 @@ pattern:

For the common case of matching a pattern and returning from the
function, use
`let else <https://doc.rust-lang.org/rust-by-example/flow_control/let_else.html>`__.
:url:`let else <https://doc.rust-lang.org/rust-by-example/flow_control/let_else.html>`.
The "else" case must diverge (``return``, ``break``, or panic - anything
but falling off the end of the block).

Expand Down Expand Up @@ -80,7 +80,7 @@ but falling off the end of the block).
}

Like with ``if let``, there is a
`while let <https://doc.rust-lang.org/reference/expressions/loop-expr.html#predicate-pattern-loops>`__
:url:`while let <https://doc.rust-lang.org/reference/expressions/loop-expr.html#predicate-pattern-loops>`
variant which repeatedly tests a value against a pattern:

.. raw:: html
Expand All @@ -98,7 +98,7 @@ variant which repeatedly tests a value against a pattern:
}

Here
`String::pop <https://doc.rust-lang.org/stable/std/string/struct.String.html#method.pop>`__
:url:`String::pop <https://doc.rust-lang.org/stable/std/string/struct.String.html#method.pop>`
returns ``Some(c)`` until the string is empty, after which it will
return ``None``. The ``while let`` lets us keep iterating through all
items.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ Key Points:
- This might be a good time to demonstrate how the ``&self`` differs
from ``self`` by trying to run ``finish`` twice.
- Beyond variants on ``self``, there are also
`special wrapper types <https://doc.rust-lang.org/reference/special-types-and-traits.html>`__
:url:`special wrapper types <https://doc.rust-lang.org/reference/special-types-and-traits.html>`
allowed to be receiver types, such as ``Box<Self>``.

.. raw:: html
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Details
---------

- The ``From`` trait will be covered later in the course, but its
`definition in the std docs <https://doc.rust-lang.org/std/convert/trait.From.html>`__
:url:`definition in the std docs <https://doc.rust-lang.org/std/convert/trait.From.html>`
is simple.

- Implementations of the trait do not need to cover all possible type
Expand All @@ -54,7 +54,7 @@ Details
match for any type T. Unlike some other languages, Rust has no
heuristic for choosing the "most specific" match. There is work on
adding this support, called
`specialization <https://rust-lang.github.io/rfcs/1210-impl-specialization.html>`__.
:url:`specialization <https://rust-lang.github.io/rfcs/1210-impl-specialization.html>`.

.. raw:: html

Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Details
implementation to use.

- When using ``dyn Trait``, it instead uses dynamic dispatch through a
`virtual method table <https://en.wikipedia.org/wiki/Virtual_method_table>`__
:url:`virtual method table <https://en.wikipedia.org/wiki/Virtual_method_table>`
(vtable). This means that there's a single version of ``fn dynamic``
that is used regardless of what type of ``Pet`` is passed in.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Exercise: Generic ``min``

In this short exercise, you will implement a generic ``min`` function
that determines the minimum of two values, using the
`Ord <https://doc.rust-lang.org/stable/std/cmp/trait.Ord.html>`__
:url:`Ord <https://doc.rust-lang.org/stable/std/cmp/trait.Ord.html>`
trait.

.. code:: rust,compile_fail
Expand All @@ -26,9 +26,9 @@ Details
---------

- Show students the
`Ord <https://doc.rust-lang.org/stable/std/cmp/trait.Ord.html>`__
:url:`Ord <https://doc.rust-lang.org/stable/std/cmp/trait.Ord.html>`
trait and
`Ordering <https://doc.rust-lang.org/stable/std/cmp/enum.Ordering.html>`__
:url:`Ordering <https://doc.rust-lang.org/stable/std/cmp/enum.Ordering.html>`
enum.

.. raw:: html
Expand Down
12 changes: 6 additions & 6 deletions courses/comprehensive_rust_training/110_std_types/02_docs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ Documentation
Rust comes with extensive documentation. For example:

- All of the details about
`loops <https://doc.rust-lang.org/stable/reference/expressions/loop-expr.html>`__.
:url:`loops <https://doc.rust-lang.org/stable/reference/expressions/loop-expr.html>`.
- Primitive types like
`u8 <https://doc.rust-lang.org/stable/std/primitive.u8.html>`__.
:url:`u8 <https://doc.rust-lang.org/stable/std/primitive.u8.html>`.
- Standard library types like
`Option <https://doc.rust-lang.org/stable/std/option/enum.Option.html>`__
:url:`Option <https://doc.rust-lang.org/stable/std/option/enum.Option.html>`
or
`BinaryHeap <https://doc.rust-lang.org/stable/std/collections/struct.BinaryHeap.html>`__.
:url:`BinaryHeap <https://doc.rust-lang.org/stable/std/collections/struct.BinaryHeap.html>`.

Use ``rustup doc --std`` or https://std.rs to view the documentation.

Expand All @@ -34,8 +34,8 @@ In fact, you can document your own code:
}

The contents are treated as Markdown. All published Rust library crates
are automatically documented at `docs.rs <https://docs.rs>`__ using
the `rustdoc <https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html>`__
are automatically documented at :url:`docs.rs <https://docs.rs>` using
the :url:`rustdoc <https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html>`
tool. It is idiomatic to document all public items in an API using this
pattern.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Option

We have already seen some use of ``Option<T>``. It stores either a value
of type ``T`` or nothing. For example,
`String::find <https://doc.rust-lang.org/stable/std/string/struct.String.html#method.find>`__
:url:`String::find <https://doc.rust-lang.org/stable/std/string/struct.String.html#method.find>`
returns an ``Option<usize>``.

.. code:: rust,editable,should_panic
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ String
String
--------

`String <https://doc.rust-lang.org/std/string/struct.String.html>`__
:url:`String <https://doc.rust-lang.org/std/string/struct.String.html>`
is a growable UTF-8 encoded string:

.. code:: rust,editable
Expand All @@ -26,7 +26,7 @@ is a growable UTF-8 encoded string:
}

``String`` implements
`Deref<Target = str> <https://doc.rust-lang.org/std/string/struct.String.html#deref-methods-str>`__,
:url:`Deref<Target = str> <https://doc.rust-lang.org/std/string/struct.String.html#deref-methods-str>`,
which means that you can call all ``str`` methods on a ``String``.

.. raw:: html
Expand All @@ -43,7 +43,7 @@ Details
- ``String::chars`` returns an iterator over the actual characters.
Note that a ``char`` can be different from what a human will consider
a "character" due to
`grapheme clusters <https://docs.rs/unicode-segmentation/latest/unicode_segmentation/struct.Graphemes.html>`__.
:url:`grapheme clusters <https://docs.rs/unicode-segmentation/latest/unicode_segmentation/struct.Graphemes.html>`.
- When people refer to strings they could either be talking about
``&str`` or ``String``.
- When a type implements ``Deref<Target = T>``, the compiler will let
Expand All @@ -67,7 +67,7 @@ Details
character boundaries or not.

- Many types can be converted to a string with the
`to_string <https://doc.rust-lang.org/std/string/trait.ToString.html#tymethod.to_string>`__
:url:`to_string <https://doc.rust-lang.org/std/string/trait.ToString.html#tymethod.to_string>`
method. This trait is automatically implemented for all types that
implement ``Display``, so anything that can be formatted can also be
converted to a string.
Expand Down
4 changes: 2 additions & 2 deletions courses/comprehensive_rust_training/110_std_types/06_vec.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
``Vec``
---------

`Vec <https://doc.rust-lang.org/std/vec/struct.Vec.html>`__ is the
:url:`Vec <https://doc.rust-lang.org/std/vec/struct.Vec.html>` is the
standard resizable heap-allocated buffer:

.. code:: rust,editable
Expand Down Expand Up @@ -34,7 +34,7 @@ standard resizable heap-allocated buffer:
}

``Vec`` implements
`Deref<Target = [T]> <https://doc.rust-lang.org/std/vec/struct.Vec.html#deref-methods-%5BT%5D>`__,
:url:`Deref<Target = [T]> <https://doc.rust-lang.org/std/vec/struct.Vec.html#deref-methods-%5BT%5D>`,
which means that you can call slice methods on a ``Vec``.

.. raw:: html
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Details
macro.

- Although, since Rust 1.56, HashMap implements
`From<[(K, V); N]> <https://doc.rust-lang.org/std/collections/hash_map/struct.HashMap.html#impl-From%3C%5B(K,+V);+N%5D%3E-for-HashMap%3CK,+V,+RandomState%3E>`__,
:url:`From<[(K, V); N]> <https://doc.rust-lang.org/std/collections/hash_map/struct.HashMap.html#impl-From%3C%5B(K,+V);+N%5D%3E-for-HashMap%3CK,+V,+RandomState%3E>`,
which allows us to easily initialize a hash map from a literal
array:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Exercise: Counter

In this exercise you will take a very simple data structure and make it
generic. It uses a
`std::collections::HashMap <https://doc.rust-lang.org/stable/std/collections/struct.HashMap.html>`__
:url:`std::collections::HashMap <https://doc.rust-lang.org/stable/std/collections/struct.HashMap.html>`
to keep track of which values have been seen and how many times each one
has appeared.

Expand All @@ -17,7 +17,7 @@ The initial version of ``Counter`` is hard coded to only work for
value being tracked, that way ``Counter`` can track any type of value.

If you finish early, try using the
`entry <https://doc.rust-lang.org/stable/std/collections/struct.HashMap.html#method.entry>`__
:url:`entry <https://doc.rust-lang.org/stable/std/collections/struct.HashMap.html#method.entry>`
method to halve the number of hash lookups required to implement the
``count`` method.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Operators
-----------

Operator overloading is implemented via traits in
`std::ops <https://doc.rust-lang.org/std/ops/index.html>`__:
:url:`std::ops <https://doc.rust-lang.org/std/ops/index.html>`:

.. code:: rust,editable

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
-----------------------

Types implement
`From <https://doc.rust-lang.org/std/convert/trait.From.html>`__ and
`Into <https://doc.rust-lang.org/std/convert/trait.Into.html>`__ to
:url:`From <https://doc.rust-lang.org/std/convert/trait.From.html>` and
:url:`Into <https://doc.rust-lang.org/std/convert/trait.Into.html>` to
facilitate type conversions. Unlike ``as``, these traits correspond to
lossless, infallible conversions.

Expand All @@ -22,9 +22,9 @@ lossless, infallible conversions.
println!("{s}, {addr}, {one}, {bigger}");
}

`Into <https://doc.rust-lang.org/std/convert/trait.Into.html>`__ is
:url:`Into <https://doc.rust-lang.org/std/convert/trait.Into.html>` is
automatically implemented when
`From <https://doc.rust-lang.org/std/convert/trait.From.html>`__ is
:url:`From <https://doc.rust-lang.org/std/convert/trait.From.html>` is
implemented:

.. code:: rust,editable
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
``Read`` and ``Write``
------------------------

Using `Read <https://doc.rust-lang.org/std/io/trait.Read.html>`__
Using :url:`Read <https://doc.rust-lang.org/std/io/trait.Read.html>`
and
`BufRead <https://doc.rust-lang.org/std/io/trait.BufRead.html>`__,
:url:`BufRead <https://doc.rust-lang.org/std/io/trait.BufRead.html>`,
you can abstract over ``u8`` sources:

.. code:: rust,editable
Expand All @@ -30,7 +30,7 @@ you can abstract over ``u8`` sources:
}

Similarly,
`Write <https://doc.rust-lang.org/std/io/trait.Write.html>`__ lets
:url:`Write <https://doc.rust-lang.org/std/io/trait.Write.html>` lets
you abstract over ``u8`` sinks:

.. code:: rust,editable
Expand Down
Loading
Loading