1
0
mirror of https://github.com/google/comprehensive-rust.git synced 2024-12-16 14:53:28 +02:00
Commit Graph

42 Commits

Author SHA1 Message Date
Max Heller
9ed01cca77
Render book as PDF in publish.yml workflow (#1572)
Renders the book as a PDF and includes it in the published HTML bundle
as `comprehensive-rust.pdf`.

Closes #1543
2024-01-15 23:02:05 +01:00
Masanori Tani
4cb12d0073
fix mdbook redirection table (#1635)
Link `overloading` in Speaker note in URL:
https://google.github.io/comprehensive-rust/hello-world/hello-world.html
is broken.

- broken:
https://google.github.io/comprehensive-rust/hello-world/basic-syntax/functions-interlude.html
(404)
- correct:
https://google.github.io/comprehensive-rust/control-flow-basics/functions.html

The reason why it is broken is below.

Original markdown is here
43474d27d1/src/hello-world/hello-world.md (L36-L37)

```
[overloading](basic-syntax/functions-interlude.md)
```

Page path is `/hello-world/hello-world.html`, so overloading link become
`/hello-world/basic-syntax/functions-interlude.html`, which is 404.

I feel it is better to use redirect to exact path, so I edit `book.toml`
and make link redirect to `/basic-syntax/functions-interlude.html`,
which re-redirect to path `/control-flow-basics/functions.html`


43474d27d1/book.toml (L114)
2024-01-04 14:05:49 +00:00
Martin Geisler
fca968651e
Fix mdbook redirection table (#1567)
There must have been a merge conflict at some point which resulted in a
malformed table. The result was that most redirects were blindly ignored
by `mdbook`.

I noticed it for
https://google.github.io/comprehensive-rust/enums.html which stopped
working because of this.

I took out the memory management redirect since we already have a file
where redirect would be (`mdbook` helpfully emits an error in this
case).
2023-12-07 15:51:42 +00:00
Martin Geisler
97b18e8538
mdbook-course: Make printing summary optional (#1562)
There is now a new “verbose” setting which can be used to print the
summary when desired.
2023-12-06 12:57:18 -05:00
Dustin J. Mitchell
6d19292f16
Comprehensive Rust v2 (#1073)
I've taken some work by @fw-immunant and others on the new organization
of the course and condensed it into a form amenable to a text editor and
some computational analysis. You can see the inputs in `course.py` but
the interesting bits are the output: `outline.md` and `slides.md`.

The idea is to break the course into more, smaller segments with
exercises at the ends and breaks in between. So `outline.md` lists the
segments, their duration, and sums those durations up per-day. It shows
we're about an hour too long right now! There are more details of the
segments in `slides.md`, or you can see mostly the same stuff in
`course.py`.

This now contains all of the content from the v1 course, ensuring both
that we've covered everything and that we'll have somewhere to redirect
every page.

Fixes #1082.
Fixes #1465.

---------

Co-authored-by: Nicole LeGare <dlegare.1001@gmail.com>
Co-authored-by: Martin Geisler <mgeisler@google.com>
2023-11-29 16:39:24 +01:00
Amin Sharifi
8f42baf968
Fixture code and footer content tags in rtl content (#1433)
Part of #671 
and #1413

In the code part of content which always is in english and must be
`text-align: left` but with `<html ... dir=rtl >` cuz conflict.

---------

Co-authored-by: Kaveh <hamidrkp@riseup.net>
2023-10-31 07:37:04 +01:00
Martin Geisler
a38a33c8fb
Use AND between words in mdbook search (#1306)
The default is to use `OR`, which I find counter-intuitive: the more I
try to narrow down a search, the more hits I get. See the full
documentation for more options:


https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlsearch
2023-10-05 10:17:05 -04:00
Hatim Nalawala
cc0a78ed9a
Move CSS files into theme/ folder (#1229)
Hi all,
This PR fixes https://github.com/google/comprehensive-rust/issues/1226:

* Moved CSS files to `theme/css`
* Moved speaker-notes.js to `theme/`
* Updated paths in book.toml
2023-09-21 11:00:27 +02:00
Dustin J. Mitchell
4815264e2d
Add mdbook-course to handle parsing frontmatter (#1224)
In v2 of the course, I'd like to include an estimate of the time to be
spent on each segment in the Markdown file. I think a good place for
such metadata is in the frontmatter.

For review purposes, though, I just want to display that information.
So, this is a start at a new mdbook preprocessor that just separates out
the frontmatter and includes it in a `<pre>` block. Eventually, I'd like
to parse it and put the time in the speaker notes.

---------

Co-authored-by: Martin Geisler <martin@geisler.net>
2023-09-20 10:01:53 -04:00
Frances Wingerter
d3a90373b0
Reorder material on first two days (#913)
- Morning of Day 1 still introduces the language and its high-level
goals/value proposition, and starts with the built-in data types Rust
provides, and how you define a function. 
- Afternoon of Day 1 gets a front loading of the basic control flow
structures in Rust but not the more exotic ones.
- The exercises for day 1 afternoon will be the Luhn algorithm (where we
can match on digits and enums such as `Option`.
- Morning of day 2 still has discussion of memory management.

Fixes #510.

---------

Co-authored-by: Martin Geisler <mgeisler@google.com>
2023-08-25 17:42:31 +02:00
Martin Geisler
8d9fddd92f
Rename welcome.md to index.md (#1039)
When building the book, mdBook will always generate an `index.html`
page for first page of the book. This meant that we had the same
content available under two different names:

- `welcome.html`: this is what the TOC would link to, and
- `index.html` or simply `/`: this is what search engines link to

Renaming the page and setting up a redirect should fix this confusion.
We still don’t have a good way of avoiding links to the `index.html`
page, but this should fix the first half of the problem.

I tested this for translations as well by building the output in a
subdirectory and serving the parent directory.

Part of #847.
2023-07-28 17:27:31 +02:00
Martin Geisler
d1d29283ba
Remove ineffective LICENSE link (#850)
Just like the Markdown files in #846, we cannot generate a redirect
for the LICENSE file this way. The broken link was fixed in #813, so
we should be fine here.
2023-06-22 16:27:56 +02:00
Martin Geisler
a3ef74f107
Remove .md redirects from book.toml (#846)
Those redirects don't actually work: they are not given a `Content-Type` by GitHub and so the browser doesn't threat them as HTML and won't follow any redirect.
2023-06-21 09:47:39 +01:00
Martin Geisler
0e09a1c569
Add redirects for all broken links to book.toml (#814)
This should clean up the list of 404 errors in the Search Console.
2023-06-14 10:21:22 +01:00
Martin Geisler
d71ea715bb
Fix broken link in for-expressions.md (#812) 2023-06-13 17:43:08 +00:00
Martin Geisler
7c9195ba7a
Fix broken link in Pitfalls of async/await (#811)
Fix broken link in Async Pitfalls
2023-06-13 17:26:56 +00:00
Florin Iucha
d7efbbbe8a
Display line numbers for code examples (#664)
This makes it easier to refer to a specific line of code while teaching or collaborating on a code snippet.
2023-05-24 07:25:18 +00:00
rbehjati
83663daaa2
Add the description of the chat-app exercise (#641)
* Adds a description of the async chat exercise
* Simplifies the use of Error in chat-async
* Links the solution to the async chat exercise
* Removes the elevator exercise
2023-05-17 18:22:11 +01:00
Martin Geisler
1274260201
Fix broken link to trait objects (#633) 2023-05-15 15:06:50 +01:00
Martin Geisler
d56298fc84
Add redirect for old async/concurrency/ directory (#635)
It seems we had a link to async/concurrency/channels.html for a brief
period. This got indexed and now show up as 404 errors in my reports.
2023-05-15 15:05:28 +01:00
Martin Geisler
661f51b06b
Fix page redirects (#620)
* Fix broken redirects

A few of these were wrong since they assumed the target path is
relative to the root of the course (the path is relative to the page
being redirected).

* Sort redirects
2023-05-08 16:31:54 +02:00
Martin Geisler
3b21053ff2
Cleanup references to "Day 4" (#603)
* Align outline with new spin-off course structure

With the new structure, the section on Android is a spin-off course
from the main 3-day course on Rust Fundamentals. The Bare-metal and
Concurrency days are spin-off courses in the same way.

* Explain new course structure

* Align Bare-Metal welcome page with other deep dives

* Merge Day 4 page into Course Structure page

* Remove Day 4 Welcome page

This aligns the Concurrency in Rust section with the Bare-Metal Rust
deep dive.

* Show subsections for Android deep dive

This aligns the Rust in Android section with the other deep dives.

* Clean up welcome page and README

We now cover async Rust and the course is no longer a four day course.

* Remove reference to the old Day 4

* Remove Day 4 references from exercises
2023-05-02 08:02:28 +02:00
Andrew Walbran
86d8c4ae54 Rename exercise template directory and archive. 2023-04-05 16:28:07 +01:00
Andrew Walbran
b6f5ba1af0 Run exerciser as mdbook renderer. 2023-04-05 16:28:07 +01:00
rbehjati
739b3a01e0
Restructure Day-3 morning (#503)
* Restructure Day-3 morning
2023-03-30 13:25:34 +01:00
Dustin J. Mitchell
bfed596d28
Generalize the day-4 afternoon (#487)
* Generalize the day-4 afternoon

This is in preparation for adding more options for this portion of the
course, and reflects an existing practice of substituting other
materials for this last half-day.

* address review comments
2023-03-10 09:07:36 -05:00
Martin Geisler
449ead5575
Integrate GA4 code directly with book.js (#470)
* Integrate GA4 code directly with `book.js`

The main advantage of this is that it simplifies the setup since we
can avoid the monkey-patching we did before.

A secondary advantage is that it should make things a little faster
since we avoid a request to the server on every page load.

* Remove unreachable return

* Watch all of `third_party`

It just occurred to me that we want to refresh the page in `mdbook serve` when anything changes in `third_party`.
2023-03-02 17:50:37 +00:00
Jooyung Han
e4205b3ac8
Remove renderers from links and index preprocessors (#464)
* Remove `renderers` from `links` and `index` preprocessors

These two preprocessors are default preprocessors and controlled by
`build.use_default_preprocessors` not by `renders`.

* Fix the order of preprocessors

I was wrong about the order in #461.

* Remove `links` and `index` preprocessor lines

These default preprocessors are run by default.

---------

Co-authored-by: Jooyung Han <jooyung@google.com>
2023-03-02 18:01:24 +09:00
Jooyung Han
1821a3fd12
Make i18n-helpers a requirement (#461)
* Make i18n-helpers a requirement

* Skip mdbook-gettext for mdbook-xgettext

* Gettext finds PO file based on `book.language`

* Update workflow

No need to set `preprocessor.gettext.po-file`.

---------

Co-authored-by: Jooyung Han <jooyung@google.com>
2023-02-28 22:05:09 +09:00
Jooyung Han
b6a55e419c
svgbob should run after gettext (#429)
svgbob translates `_text_` into `*text*`, which makes gettext fail to
translate paragraphs with `_text_`.

Co-authored-by: Jooyung Han <jooyung@google.com>
2023-02-17 16:49:34 +01:00
Jooyung Han
a6bbd1e64e
links should run before gettext (#421)
fixes #419

Co-authored-by: Jooyung Han <jooyung@google.com>
2023-02-17 09:56:51 +09:00
Martin Geisler
3b7123d21a
Add language picker menu (#411)
The picker is a drop-down menu using the same design as the theme
picker in the top-left.

There doesn’t seem to be an easy way to pass in a list of languages
and descriptions, so for now we’ll have to expand the menu by hand as
we add new languages. A comment has been added to `publish.yml` to
remind us of this.
2023-02-15 15:10:16 +01:00
Martin Geisler
f9dea3d7a3
Setup redirects after #120 and #177 (#352)
This makes `mdbook` output a simple redirect at the location of the
old pages. I’ll try to add such pages when we shuffle around our
pages to make sure external links stay valid.
2023-02-06 17:10:01 +01:00
Martin Geisler
ee36ae318f
Add an aspect-ratio-helper mdbook preprocessor (#187)
The idea is that this will help us make better slides: we can see at a
glance when the slide becomes too full.
2023-01-27 18:30:37 +01:00
Martin Geisler
46f25ac891
Set the site-url to fix 404 page on GitHub Pages (#263)
This fixes the 404 page on GitHub Pages: the default is `/`, but we’re
hosting the site from a subdirectory because of how the repository is
setup.

Fixes #178.
2023-01-24 12:03:46 +01:00
Martin Geisler
dbc11b2df2
Watch po/ directory for changes (#188)
This makes `mdbook serve` automatically reload the page when
translations change.
2023-01-20 11:36:14 +01:00
Martin Geisler
48ec773052 Add support for translations
This implements a translation pipeline using the industry-standard
Gettext[1] system.

I picked Gettext for the reasons described in [2] and [3]:

* It’s widely used in open source software. This means that there are
  graphical editors which will help you in editing the `.po` files. An
  example is Poedit[4], which is available for all major platforms.

  There are also many online systems for doing translations. An
  example is Pontoon[5], which is used for the Rust website itself. We
  can consider setting up such an instance ourselves.

* It is a light-weight yet structured format. This means that nothing
  changes with regards to how you update the original English text. We
  can still accept fixes and PRs like normal.

  The structure means that translators can see exactly which part of
  the course they need to update after a change. This is completely
  lost if you simply copy over the original text and translate it
  in-place in the Markdown files.

The code here only adds support for translations. They are not yet
tested, published or used for anything. Next steps will be:

* Add support for switching languages via a bit of JavaScript on each
  page.

* Update the speaker notes feature to support translations (right now
  “Speaker Notes” is hard-coded into the generated HTML). I think we
  should turn it into a mdbook preprocessor instead.

* Add testing: We should test that the `.po` files are well-formed. We
  should also run `mdbook test` on each language since the
  translations can alter the embedded code.

Fixes #115.

[1]: https://www.gnu.org/software/gettext/manual/html_node/index.html
[2]: https://github.com/rust-lang/mdBook/pull/1864
[3]:
https://github.com/rust-lang/mdBook/issues/5#issuecomment-1144887806
[4]: https://poedit.net/
[5]: https://pontoon.rust-lang.org/
2023-01-18 16:12:53 +01:00
Martin Geisler
d5359fa92a Add support for speaker notes
This implements a system for speaker notes via `details` elements and
some JavaScript. The general idea is

1. You add speaker notes to each page by wrapping some Markdown code
   in `<details> … </details>`. This is a standard HTML element for,
   well extra details. Browsers will render the element with a toggle
   control for showing/hiding the content.

2. We inject JavaScript on every page which finds these speaker note
   elements. They’re styled slightly and we keep their open/closed
   state in a browser local storage. This ensures that you can keep
   them open/closed across page loads.

3. We add a link to the speaker notes which will open in a new tab.
   The URL is amended with `#speaker-notes-open`, which we detect in
   the new tab: we hide the other content in this case.
   Simultaneously, we hide the speaker notes in the original window.

4. When navigating to a new page, we signal this to the other window.
   We then navigate to the same page. The logic above kicks in and
   hides the right part of the content. This lets the users page
   through the course using either the regular window or the speaker
   notes — the result is the same and both windows stay in sync.

Tested in both Chrome and Firefox. When using a popup speaker note
window, the content loads more smoothly in Chrome, but it still works
fine in Firefox.

Fixes #53.
2023-01-05 07:46:18 +01:00
Dylan
2ce32238b5 Fix svgbob diagrams in dark mode 2022-12-27 17:04:14 +01:00
Martin Geisler
ced70fce79 Add links to edit every page on GitHub
This makes it super easy to edit a page: just click the icon in the
top-right and you’ll be taken directly to an editor on GitHub.
2022-12-21 17:29:56 +01:00
Martin Geisler
53f0674756 Link back to repository in top-right corner 2022-12-21 17:28:02 +01:00
Martin Geisler
c212a473ba Publish Comprehensive Rust 🦀 2022-12-21 16:38:28 +01:00