From aafbc5a9b801a0c67a059ccc7e33775fe374e311 Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Sat, 6 Sep 2025 18:35:01 +0200 Subject: [PATCH 1/3] Add a GEMINI.md file with instructions for the CLI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I’ve been playing with the `gemini` CLI tool recently (https://google-gemini.github.io/gemini-cli/) and learned that it will read instructions from it’s own kind of README. So I asked it to generate one and use it as a basis for this file. I took the liberty to expand the style guide a little at the same time to incorporate that instructions I gave Gemini while generating the many language fixing PRs[1]. [1]: https://github.com/google/comprehensive-rust/pulls?q=author%3Amgeisler+%22improve+language%22 --- GEMINI.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ STYLE.md | 32 ++++++++++++++++------- 2 files changed, 101 insertions(+), 9 deletions(-) create mode 100644 GEMINI.md diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 000000000000..28c8cd360395 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,78 @@ +# Project Overview + +This repository contains the source code for Comprehensive Rust, a family of +courses on Rust developed by Google. The project is a Rust workspace that +leverages `mdbook` to generate a comprehensive course website, including various +deep dives into specialized topics like Android, Chromium, bare-metal +development, and concurrency. + +## Key Technologies + +- **Rust:** The primary programming language for the course content, custom + tools, and examples. +- **mdbook:** A command-line tool to create books from Markdown files, used for + generating the course website. +- **Custom mdbook Preprocessors:** `mdbook-course` and `mdbook-exerciser` are + Rust binaries that extend `mdbook`'s functionality, for example, to extract + exercise starter code. +- **`cargo xtask`:** A custom binary within the workspace used for project + automation, simplifying common development tasks. + +# Building and Running + +The project uses `cargo xtask` for all build and development automation. + +## Setup + +1. **Install Rust:** Follow the instructions on + [https://rustup.rs/](https://rustup.rs/). +2. **Clone Repository:** + ```bash + git clone https://github.com/google/comprehensive-rust/ + cd comprehensive-rust + ``` +3. **Install Project Tools:** + ```bash + cargo xtask install-tools + ``` + +## Commands + +All commands are run using `cargo xtask`. Run `cargo xtask --help` for a full +list of options. + +- **Serve the Course Locally:** Starts a web server to view the course content. + ```bash + cargo xtask serve [--language ] [--output ] + ``` + (e.g., `cargo xtask serve -l da` for the Danish translation) + +- **Build the Course:** Creates a static version of the course in the `book/` + directory. + ```bash + cargo xtask build [--language ] [--output ] + ``` + +- **Run Rust Snippet Tests:** Tests all Rust code snippets included in the + course material. + ```bash + cargo xtask rust-tests + ``` + +- **Run Web Driver Tests:** Executes web driver tests located in the `tests/` + directory. + ```bash + cargo xtask web-tests [--dir ] + ``` + +# Development Conventions + +- **Project Automation:** `cargo xtask` is the primary interface for common + development tasks. +- **Course Content:** Markdown files in the `src/` directory, structured + according to `src/SUMMARY.md`. +- **Code Formatting:** `dprint fmt` is used to format all source files according + to `rustfmt.toml` and `dprint.json`. +- **Contributions:** Refer to `CONTRIBUTING.md` for guidelines on contributing + to the project. +- **Style:** Refer to `STYLE.md` for style guidelines. diff --git a/STYLE.md b/STYLE.md index c405a1995795..0829f3712f6d 100644 --- a/STYLE.md +++ b/STYLE.md @@ -28,7 +28,7 @@ notes (see below). ### Rust Code -When showing Rust code, please use the same spacing as `rustfmt`: `3 * x` +When showing Rust code inline, please use the same spacing as `rustfmt`: `3 * x` instead of `3*x`. However, feel free to remove newlines when it can make the code more compact and easier to understand, e.g., you can use @@ -40,9 +40,21 @@ struct Person { name: String } -if the `Person` struct is not important for your example. Please use this -sparingly: enclose the code block in `` and -`` to suppress warnings about the formatting. +Please use this sparingly: enclose the code block in +`` and `` to suppress the +automatic formatting. + +### Language and Tone + +The courses are written in American English, so write "initialize", not +"initialise". + +Use an informal, friendly, and concise tone. Remember that the courses are meant +to be taught by experienced programmer to other experienced programmers. We +expect familiarity with programming, typically in a statically compiled language +like Java or C++. We don't explain common concepts known from that family of +languages, but we cannot assume familiarity with things like functional +programming. ## Speaker Notes @@ -50,6 +62,9 @@ We have extended `mdbook` with support for speaker notes: content added between `
...
` tags is rendered in a special box that can be collapsed or removed entirely from the slide. +- Unlike the main content, the speaker notes don't have to fit on a single + slide. + - The speaker notes should expand on the topic of the slide. Use them to provide interesting background information for both the instructor and for students who look at the material outside of a class. Remember that many more people @@ -57,8 +72,7 @@ collapsed or removed entirely from the slide. when there is no Rust expert around. - Avoid using speaker notes as a script for the instructor. When teaching the - course, instructors will only have time to glance at the notes so it is not - useful to include full paragraphs which the instructor should read out loud. + course, instructors will only have a short time to glance at the notes. ### More to Explore @@ -100,6 +114,6 @@ When translating the course, please take the following into account: and `**strong emphasis**` like in the original. - If you find mistakes or things that sound awkward in the original English - text, please submit PRs to fix them! Fixing typos in the translation is great, - but we want everybody to benefit from the fixes and that is why we need the - fix to be made in the English text too. + text, please submit PRs to fix them in the English text! Fixing typos in the + translation is great, but we want everybody to benefit from the fixes and that + is why we need the fix to be made in the English text too. From 44a13ca92420ee845f8a1904343459cc78267116 Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Sat, 6 Sep 2025 19:17:39 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Dmitri Gribenko --- GEMINI.md | 10 +++++----- STYLE.md | 14 +++++++------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index 28c8cd360395..d216aa986cb9 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,14 +1,14 @@ # Project Overview This repository contains the source code for Comprehensive Rust, a family of -courses on Rust developed by Google. The project is a Rust workspace that -leverages `mdbook` to generate a comprehensive course website, including various +courses on Rust developed by Google, starting with Rust foundations, and including deep dives into specialized topics like Android, Chromium, bare-metal -development, and concurrency. +development, and concurrency. The project is a Rust workspace that +leverages `mdbook` to generate a course website. ## Key Technologies -- **Rust:** The primary programming language for the course content, custom +- **Rust:** The primary programming language for the course subject, custom tools, and examples. - **mdbook:** A command-line tool to create books from Markdown files, used for generating the course website. @@ -20,7 +20,7 @@ development, and concurrency. # Building and Running -The project uses `cargo xtask` for all build and development automation. +The project uses `cargo xtask` for project-specific automation, like builds, tests, and managing translations. ## Setup diff --git a/STYLE.md b/STYLE.md index 0829f3712f6d..4c309069fd32 100644 --- a/STYLE.md +++ b/STYLE.md @@ -30,7 +30,7 @@ notes (see below). When showing Rust code inline, please use the same spacing as `rustfmt`: `3 * x` instead of `3*x`. However, feel free to remove newlines when it can make the -code more compact and easier to understand, e.g., you can use +code more compact and easier to understand, e.g., you can define a struct on one line if it is not the focus of your example: @@ -40,9 +40,9 @@ struct Person { name: String } -Please use this sparingly: enclose the code block in +Enclose the code block in `` and `` to suppress the -automatic formatting. +automatic formatting. Please use this sparingly. ### Language and Tone @@ -50,8 +50,8 @@ The courses are written in American English, so write "initialize", not "initialise". Use an informal, friendly, and concise tone. Remember that the courses are meant -to be taught by experienced programmer to other experienced programmers. We -expect familiarity with programming, typically in a statically compiled language +to be taught by an experienced programmer to other experienced programmers. We +expect familiarity with programming, typically in a statically typed language like Java or C++. We don't explain common concepts known from that family of languages, but we cannot assume familiarity with things like functional programming. @@ -71,8 +71,8 @@ collapsed or removed entirely from the slide. will read the course by themselves, so make the notes complete and useful even when there is no Rust expert around. -- Avoid using speaker notes as a script for the instructor. When teaching the - course, instructors will only have a short time to glance at the notes. +- Speaker notes are not a script for the instructor. When teaching the + course, instructors only have a short time to glance at the notes. Don't include full paragraphs for the instructor to read out loud. ### More to Explore From b712bd6d07fa6b2bb823ad87a8f463eb6051f99e Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Sat, 6 Sep 2025 20:47:02 +0200 Subject: [PATCH 3/3] Fix formatting --- GEMINI.md | 11 ++++++----- STYLE.md | 14 ++++++++------ 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index d216aa986cb9..2d19288dcc33 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,10 +1,10 @@ # Project Overview This repository contains the source code for Comprehensive Rust, a family of -courses on Rust developed by Google, starting with Rust foundations, and including -deep dives into specialized topics like Android, Chromium, bare-metal -development, and concurrency. The project is a Rust workspace that -leverages `mdbook` to generate a course website. +courses on Rust developed by Google, starting with Rust foundations, and +including deep dives into specialized topics like Android, Chromium, bare-metal +development, and concurrency. The project is a Rust workspace that leverages +`mdbook` to generate a course website. ## Key Technologies @@ -20,7 +20,8 @@ leverages `mdbook` to generate a course website. # Building and Running -The project uses `cargo xtask` for project-specific automation, like builds, tests, and managing translations. +The project uses `cargo xtask` for project-specific automation, like builds, +tests, and managing translations. ## Setup diff --git a/STYLE.md b/STYLE.md index 4c309069fd32..58e91b851bf7 100644 --- a/STYLE.md +++ b/STYLE.md @@ -30,7 +30,8 @@ notes (see below). When showing Rust code inline, please use the same spacing as `rustfmt`: `3 * x` instead of `3*x`. However, feel free to remove newlines when it can make the -code more compact and easier to understand, e.g., you can define a struct on one line if it is not the focus of your example: +code more compact and easier to understand, e.g., you can define a struct on one +line if it is not the focus of your example: @@ -40,9 +41,9 @@ struct Person { name: String } -Enclose the code block in -`` and `` to suppress the -automatic formatting. Please use this sparingly. +Enclose the code block in `` and +`` to suppress the automatic formatting. Please use +this sparingly. ### Language and Tone @@ -71,8 +72,9 @@ collapsed or removed entirely from the slide. will read the course by themselves, so make the notes complete and useful even when there is no Rust expert around. -- Speaker notes are not a script for the instructor. When teaching the - course, instructors only have a short time to glance at the notes. Don't include full paragraphs for the instructor to read out loud. +- Speaker notes are not a script for the instructor. When teaching the course, + instructors only have a short time to glance at the notes. Don't include full + paragraphs for the instructor to read out loud. ### More to Explore