Skip to content

fix(docs): align code block styles for shell snippets #15661

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

fix(docs): align code block styles for shell snippets #15661

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/doc/contrib/src/implementation/debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ It also supports filtering for specific modules with comma-separated [directives
Feel free to use [shorthand macros] to help with diagnosing problems.
We're looking forward to making Cargo logging mechanism more structural!

```sh
```bash
# Outputs all logs with levels debug and higher
CARGO_LOG=debug cargo generate-lockfile

Comment on lines +11 to 14
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to lean towards console blocks for commands

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point as it feels shell-independent. Will fix those!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Umm, I thought so, but seems like bash blocks works better (in terms of syntax highlighting) for multi-line commands with comments like this. How do you think about that...?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've tended to do $ #. Not great but I feel its more semantically correct than describing these as bash scripts (which is what bash means). Unsure if others have other opinions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds fair, however for especially one-liner like this, I'd prefer the ease of copy-pasting by removing leading $:

cargo/src/doc/contrib/src/tests/writing.md

Lines 224 to 226 in f6cea42

```console
$ SNAPSHOTS=overwrite cargo test
```

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that as a tooling limitation and I personally still lean towards console

Expand Down
6 changes: 3 additions & 3 deletions src/doc/contrib/src/tests/profiling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ At process exit, your trace will be in a file like `trace-1668480819035032.json`
Open that file with [ui.perfetto.dev](https://ui.perfetto.dev) (or chrome://tracing) to browse your trace.

Example:
```console
$ # Output first three levels of profiling info
$ CARGO_LOG_PROFILE=true cargo generate-lockfile
```bash
# Output first three levels of profiling info
CARGO_LOG_PROFILE=true cargo generate-lockfile
```

**Note:** This is intended for the development of cargo and there are no compatibility guarantees on this functionality.
Expand Down
24 changes: 14 additions & 10 deletions src/doc/contrib/src/tests/writing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,8 +221,8 @@ Then populate

The project, stdout, and stderr snapshots can be updated by running with the
`SNAPSHOTS=overwrite` environment variable, like:
```console
$ SNAPSHOTS=overwrite cargo test
```bash
SNAPSHOTS=overwrite cargo test
```

Be sure to check the snapshots to make sure they make sense.
Expand Down Expand Up @@ -265,18 +265,22 @@ expect, or you just generally want to experiment within the sandbox
environment. The general process is:

1. Build the sandbox for the test you want to investigate. For example:

`cargo test --test testsuite -- features2::inactivate_targets`.
```bash
cargo test --test testsuite -- features2::inactivate_targets
```
2. In another terminal, head into the sandbox directory to inspect the files and run `cargo` directly.
1. The sandbox directories start with `t0` for the first test.

`cd target/tmp/cit/t0`
```bash
cd target/tmp/cit/t0
```
2. Set up the environment so that the sandbox configuration takes effect:

`export CARGO_HOME=$(pwd)/home/.cargo`
```bash
export CARGO_HOME=$(pwd)/home/.cargo
```
3. Most tests create a `foo` project, so head into that:

`cd foo`
```bash
cd foo
```
3. Run whatever cargo command you want. See [Running Cargo] for more details
on running the correct `cargo` process. Some examples:

Expand Down