diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 000000000000..2d19288dcc33 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,79 @@ +# 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. + +## Key Technologies + +- **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. +- **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 project-specific automation, like builds, +tests, and managing translations. + +## 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..58e91b851bf7 100644 --- a/STYLE.md +++ b/STYLE.md @@ -28,9 +28,10 @@ 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 +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,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. +Enclose the code block in `` and +`` to suppress the automatic formatting. Please use +this sparingly. + +### 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 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. ## Speaker Notes @@ -50,15 +63,18 @@ 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 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 time to glance at the notes so it is not - useful to include full paragraphs which the instructor should 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 @@ -100,6 +116,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.