rust/comprehensive-rust
1
0
Fork 0
mirror of https://github.com/google/comprehensive-rust.git synced 2024-12-15 14:27:50 +02:00
Code Issues Releases Activity
35beb8d916
comprehensive-rust/book.toml

95 lines
3.4 KiB
TOML
Raw Normal View History

Publish Comprehensive Rust 🦀
2022-12-21 17:36:30 +02:00
[book]
authors = ["Martin Geisler"]
language = "en"
multilingual = false
src = "src"
title = "Comprehensive Rust 🦀"
[rust]
edition = "2021"
Watch `po/` directory for changes (#188) This makes `mdbook serve` automatically reload the page when translations change.
2023-01-20 12:36:14 +02:00
[build]
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 19:50:37 +02:00
extra-watch-dirs = ["po", "third_party"]
Watch `po/` directory for changes (#188) This makes `mdbook serve` automatically reload the page when translations change.
2023-01-20 12:36:14 +02:00
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 15:05:09 +02:00
[preprocessor.gettext]
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 11:01:24 +02:00
after = ["links"]
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-08 14:45:19 +02:00
Publish Comprehensive Rust 🦀
2022-12-21 17:36:30 +02:00
[preprocessor.svgbob]
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-08 14:45:19 +02:00
renderers = ["html"]
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 11:01:24 +02:00
after = ["gettext"]
Publish Comprehensive Rust 🦀
2022-12-21 17:36:30 +02:00
class = "bob"
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 16:01:53 +02:00
[preprocessor.course]
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 19:30:37 +02:00
# Enable this preprocessor to overlay a large red rectangle on the
# pages. This will show you an estimate of what the course
# participants can see during the presentation.
#
# [preprocessor.aspect-ratio-helper]
# command = "./aspect-ratio-helper.py"
Publish Comprehensive Rust 🦀
2022-12-21 17:36:30 +02:00
[output.html]
curly-quotes = true
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
additional-js = ["theme/speaker-notes.js"]
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 16:01:53 +02:00
additional-css = [
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
"theme/css/svgbob.css",
"theme/css/speaker-notes.css",
"theme/css/language-picker.css",
"theme/css/frontmatter.css",
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 08:37:04 +02:00
"theme/css/rtl.css",
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 16:01:53 +02:00
]
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 13:03:46 +02:00
site-url = "/comprehensive-rust/"
Link back to repository in top-right corner
2022-12-21 18:28:02 +02:00
git-repository-url = "https://github.com/google/comprehensive-rust"
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 18:29:56 +02:00
edit-url-template = "https://github.com/google/comprehensive-rust/edit/main/{path}"
Publish Comprehensive Rust 🦀
2022-12-21 17:36:30 +02:00
[output.html.fold]
enable = true
level = 0
[output.html.playground]
editable = true
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 09:25:18 +02:00
line-numbers = true
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 18:10:01 +02:00
[output.html.redirect]
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
# Redirects in the form of "old-path" = "new-path", where the new path
# is relative to the old path.
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 16:05:28 +02:00
"async/concurrency/channels.html" = "../channels.html"
Fix broken link in Pitfalls of `async`/`await` (#811) Fix broken link in Async Pitfalls
2023-06-13 19:26:56 +02:00
"async/pitfall/async-traits.html" = "../pitfalls/async-traits.html"
Fix broken link in for-expressions.md (#812)
2023-06-13 19:43:08 +02:00
"control-flow/while-let-expression.html" = "while-let-expressions.html"
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 11:21:22 +02:00
"exercises/day-1/soluções-tarde.html" = "solutions-afternoon.html"
"exercises/day-2/soluções-tarde.html" = "solutions-afternoon.html"
"exercises/day-3/soluções-tarde.html" = "solutions-afternoon.html"
"exercises/day-3/simples-gui.html" = "simple-gui.html"
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
"exercises/day-4/afternoon.html" = "../android/morning.html"
"exercises/day-4/android.html" = "../android/morning.html"
"exercises/day-4/dining-philosophers.html" = "../concurrency/dining-philosophers.html"
"exercises/day-4/elevator.html" = "../concurrency/elevator.html"
"exercises/day-4/link-checker.html" = "../concurrency/link-checker.html"
"exercises/day-4/morning.html" = "../concurrency/morning.html"
"exercises/day-4/solutions-morning.html" = "../concurrency/solutions-morning.html"
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 19:22:11 +02:00
"exercises/concurrency/elevator.html" = "chat-app.html"
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
"generics/closures.html" = "../traits/closures.html"
"generics/impl-trait.html" = "../traits/impl-trait.html"
"generics/trait-bounds.html" = "../traits/trait-bounds.html"
Fix broken link to trait objects (#633)
2023-05-15 16:06:50 +02:00
"generics/trait-objects.html" = "../traits/trait-objects.html"
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 11:21:22 +02:00
"outros-recursos.html" = "other-resources.html"
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
"running-the-course/day-4.html" = "course-structure.html"
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 11:21:22 +02:00
"sintaxe-básica/funções-interlude.html" = "../basic-syntax/functions-interlude.html"
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
"structure.html" = "running-the-course/course-structure.html"
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 11:21:22 +02:00
"unsafe/mutable-static-variables.md" = "mutable-static-variables.html"
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 18:10:01 +02:00
"unsafe/unsafe-functions.html" = "calling-unsafe-functions.html"
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
"welcome-bare-metal.html" = "bare-metal.html"
"welcome-day-4.html" = "concurrency.html"
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
# Moving exercises between days
"exercises/day-2/luhn.html" = "../day-1/luhn.html"
"exercises/day-2/points-polygons.html" = "../day-3/points-polygons.html"
"exercises/day-1/book-library.html" = "../day-2/book-library.html"
"exercises/day-1/iterators-and-ownership.html" = "../day-2/iterators-and-ownership.html"
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
# Send people to canonical URL instead of index.html
"welcome.html" = "./"
Run exerciser as mdbook renderer.
2023-04-03 17:18:32 +02:00
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 16:17:05 +02:00
[output.html.search]
use-boolean-and = true
Run exerciser as mdbook renderer.
2023-04-03 17:18:32 +02:00
[output.exerciser]
Rename exercise template directory and archive.
2023-04-05 17:15:42 +02:00
output-directory = "comprehensive-rust-exercises"
Reference in New Issue Copy Permalink