You've already forked comprehensive-rust
mirror of
https://github.com/google/comprehensive-rust.git
synced 2025-10-09 10:55:26 +02:00
docs(style): Reorganize code block and formatting sections (#2928)
- Consolidates all guidance related to code block mechanics under a new top-level heading, "Code Blocks Mechanics". - Moves the "Rust Code Formatting" guidance to be a subsection under this new heading. - The rest of the former "Rust Code" section is now directly under "Course Slides". This restructuring improves the logical flow of the style guide by grouping all code-related formatting and tooling conventions into a single, easy-to-find section.
This commit is contained in:
104
STYLE.md
104
STYLE.md
@@ -129,33 +129,14 @@ When introducing a new concept, start with a simple, relatable, and concrete
|
||||
example. A good opening example grounds the concept for the learner and provides
|
||||
motivation for the more detailed explanation that will follow.
|
||||
|
||||
### Rust Code
|
||||
|
||||
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:
|
||||
|
||||
<!-- dprint-ignore-start -->
|
||||
|
||||
```rust
|
||||
struct Person { name: String }
|
||||
```
|
||||
|
||||
<!-- dprint-ignore-end -->
|
||||
|
||||
Enclose the code block in `<!-- dprint-ignore-start -->` and
|
||||
`<!-- dprint-ignore-end -->` to suppress the automatic formatting. Please use
|
||||
this sparingly.
|
||||
|
||||
#### Use Meaningful Examples
|
||||
### Use Meaningful Examples
|
||||
|
||||
Code samples on the slides should be short and do something meaningful. Avoid
|
||||
using generic placeholders like `Foo`, `Bar`, and `Baz`. Using descriptive names
|
||||
from a real-world, even if simplified, domain makes the code easier to
|
||||
understand and relate to.
|
||||
|
||||
#### Interactive Code Snippets
|
||||
### Plan Interactive Code Snippets
|
||||
|
||||
All Rust code blocks in the course are not static text but are live, editable
|
||||
playgrounds. An important teaching method is for the instructor to edit these
|
||||
@@ -166,37 +147,6 @@ 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 Blocks
|
||||
|
||||
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.
|
||||
|
||||
### `mdbook` and `mdbook-course` Conventions
|
||||
|
||||
The project uses `mdbook` features in specific ways, as well as a custom
|
||||
@@ -318,6 +268,56 @@ explanation of what the resource contains and why it is relevant. A vague
|
||||
reference is not helpful, but a specific one can be a great tool for
|
||||
self-learners.
|
||||
|
||||
## Code Blocks Mechanics
|
||||
|
||||
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.
|
||||
|
||||
### Rust Code Formatting
|
||||
|
||||
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:
|
||||
|
||||
<!-- dprint-ignore-start -->
|
||||
|
||||
```rust
|
||||
struct Person { name: String }
|
||||
```
|
||||
|
||||
<!-- dprint-ignore-end -->
|
||||
|
||||
Enclose the code block in `<!-- dprint-ignore-start -->` and
|
||||
`<!-- dprint-ignore-end -->` to suppress the automatic formatting. Please use
|
||||
this sparingly.
|
||||
|
||||
## Translations
|
||||
|
||||
This section is about what you write in the translation. We describe
|
||||
|
Reference in New Issue
Block a user