1
0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-12-03 09:45:17 +02:00

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.
This commit is contained in:
Dmitri Gribenko
2025-09-23 20:17:00 +02:00
committed by GitHub
parent b183ee2f56
commit a77ea82cde
2 changed files with 32 additions and 9 deletions

View File

@@ -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