You've already forked comprehensive-rust
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:
33
STYLE.md
33
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user