From a77ea82cde49cac6d3434b76707cc765e99e42f5 Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Tue, 23 Sep 2025 20:17:00 +0200 Subject: [PATCH] feat(docs): Centralize code block style guide (#2922) - Moves the canonical documentation for code block annotations and language identifiers into STYLE.md. - Removes the redundant, partial documentation from GEMINI.md. - Updates GEMINI.md to instruct the AI assistant to always refer to STYLE.md for guidance. This change makes STYLE.md the single source of truth for all markdown and code style conventions, ensuring consistency for both human and AI contributors. --- GEMINI.md | 8 +++----- STYLE.md | 33 +++++++++++++++++++++++++++++---- 2 files changed, 32 insertions(+), 9 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index 2334d7b9..9ac25612 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -79,7 +79,9 @@ list of options. project tools with `cargo xtask install-tools`. - **Contributions:** Refer to `CONTRIBUTING.md` for guidelines on contributing to the project. -- **Style:** Refer to `STYLE.md` for style guidelines. +- **Style:** Refer to `STYLE.md` for style guidelines. When making changes to + Markdown files in `src/`, always first read `STYLE.md` and follow its + conventions. - **GitHub Actions:** The project uses composite GitHub Actions to simplify CI workflows. These actions should be preferred over hand-written commands. - **`apt-get-install`:** This action efficiently installs Debian packages. It @@ -168,7 +170,3 @@ its tasks correctly. snippet, treat it as a self-contained program. Do not assume it shares a scope or context with other snippets in the same file unless the surrounding text explicitly states otherwise. -- **Interpreting Annotations:** Annotations like `compile_fail`, `should_panic`, - and `editable` describe how a snippet is tested. For example, `compile_fail` - means the snippet is expected to fail compilation, which is useful for - demonstrating common errors. diff --git a/STYLE.md b/STYLE.md index 9d4accdf..d2c0d786 100644 --- a/STYLE.md +++ b/STYLE.md @@ -161,11 +161,36 @@ Contributors should design their slides with this interactivity in mind. The initial state of the code should be a good starting point for a live demonstration. -#### Code Annotations +### Code Blocks -Use the `ignore` annotation for code snippets that are not meant to be complete, -self-contained programs. Use `compile_fail` only when the goal is to demonstrate -a specific compiler error that is itself the lesson. +Code blocks are a critical part of the course. To ensure they are consistent and +behave as expected, please follow these conventions. + +#### Language Identifiers + +Use the following language identifiers for fenced code blocks: + +- **`rust`**: For Rust code examples. +- **`shell`**: For shell commands. Use a `$` prompt for consistency. Omit the + prompt for multi-line commands or when the output is shown. +- **`bob`**: For ASCII art diagrams generated by `mdbook-bob`. +- **`ignore`**: For code snippets that are not complete, self-contained programs + or are for illustrative purposes only and should not be compiled. + +#### mdbook Annotations + +You can add annotations to Rust code blocks to control how they are tested and +displayed: + +- **`editable`**: Makes the code block an interactive playground where users can + edit and run the code. This should be used for most Rust examples. +- **`compile_fail`**: Indicates that the code is expected to fail compilation. + This is used to demonstrate specific compiler errors. +- **`should_panic`**: Indicates that the code is expected to panic when run. +- **`warnunused`**: Re-enables `unused` lints for a code block. By default, the + course's test runner disables lints for unused variables, imports, etc., to + avoid distracting warnings. Use this annotation only when a warning is part of + the lesson. ### Language and Tone