Setup and Building: update code blocks

[hugovk]

With output

For blocks showing commands, where there's output shown, it's best to show a $ prompt and use console formatting, so they're shown with formatting:

$ git remote -v
origin  git@github.com:<your-username>/cpython.git (fetch)
origin  git@github.com:<your-username>/cpython.git (push)
upstream        git@github.com:python/cpython.git (fetch)
upstream        git@github.com:python/cpython.git (push)

(These PR message examples are shown in Markdown because GitHub, but a similar thing applies to RST in the devguide.)

No output

If there's no output shown, instead of console formatting and a prompt, it's better to use bash without a prompt.

Here's an example with console and prompts:

$ # In the CPython root:
$ docker run -v$(pwd):/src:Z -w /src --rm -it ubuntu:22.04 \
     bash /src/.github/workflows/regen-abidump.sh

And bash with no prompts:

# In the CPython root:
docker run -v$(pwd):/src:Z -w /src --rm -it ubuntu:22.04 \
     bash /src/.github/workflows/regen-abidump.sh

Why?

The biggest usability gain is when clicking the copy button at the right side of the code block: it doesn't include the $, so you can follow the guide more easily without having to carefully avoid pasting and running a $ in your terminal.

Details

• Because there's only one using console and ~21 using bash, flip the default to . highlight:: bash.

• Also -- unrelated but minor -- bump a GitHub Actions version, can drop this if desired.

Preview

• Now: https://devguide.python.org/getting-started/setup-building/

• PR: https://cpython-devguide--947.org.readthedocs.build/getting-started/setup-building/

[ezio-melotti]

The biggest usability gain is when clicking the copy button at the right side of the code block

The copybutton has a flag to strip prompts. Maybe we can enable that instead of removing the $ prompts?

One advantage of the $ prompt is that it makes it more explicit that this is a shell command -- even though here it's quite obvious, with commands like cd, git, and similar.

FWIW I usually select to copy (either drag'n'drop or triple click for individual lines) and mid-click to paste and I don't use the copybutton/ctrl+v. While selecting, both before and after the PR, the $ is not event selectable/copyable.

The highlight of the output also looks the same both before and after the changes, so it seems to me that the only effect of the PR is removing the $ from the output.

[hugovk]

Interesting idea!

I've updated the PR to use copybutton_prompt_text = "$" and switched promptless code-block:: bash to console with prompts.