Skip to content

Add syntax highlight to all shell code blocks #9445

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.

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

Merged
merged 2 commits into from
Jan 2, 2023

Conversation

Avasam
Copy link
Collaborator

@Avasam Avasam commented Jan 2, 2023

  • Using bash by default, powershell for Windows-specific
  • Added missing start-of-line markers

Please read #9434 (comment) as for the motivation why, as well as why use bash specifically (mainly for semantic reasons)

As for using powershell for Windows-specific commands over cmd/batch:

Full explanation with examples (linked comment)

As far as https://github.com/github/linguist/blob/master/lib/linguist/languages.yml#L6204 is concerned, shell, sh, shell-script, bash and zsh are all the same, and look fine.

bash

(.venv3)$ python tests/get_external_dependencies.py <third_party_stub>  # List external dependencies for <third_party_stub>
(.venv3)$ python tests/get_external_dependencies.py <third_party_stub1> <third_party_stub2>  # List external dependencies for <third_party_stub1> and <third_party_stub2>
(.venv3)$ python tests/get_external_dependencies.py  # List external dependencies for all non stubs packages in typeshed
(.venv3)$ pip install $(python tests/get_external_dependencies.py <third_party_stub>)  # Install non-types dependencies

shell

(.venv3)$ python tests/get_external_dependencies.py <third_party_stub>  # List external dependencies for <third_party_stub>
(.venv3)$ python tests/get_external_dependencies.py <third_party_stub1> <third_party_stub2>  # List external dependencies for <third_party_stub1> and <third_party_stub2>
(.venv3)$ python tests/get_external_dependencies.py  # List external dependencies for all non stubs packages in typeshed
(.venv3)$ pip install $(python tests/get_external_dependencies.py <third_party_stub>)  # Install non-types dependencies

powershell

(.venv3)$ python tests/get_external_dependencies.py <third_party_stub>  # List external dependencies for <third_party_stub>
(.venv3)$ python tests/get_external_dependencies.py <third_party_stub1> <third_party_stub2>  # List external dependencies for <third_party_stub1> and <third_party_stub2>
(.venv3)$ python tests/get_external_dependencies.py  # List external dependencies for all non stubs packages in typeshed
(.venv3)$ pip install $(python tests/get_external_dependencies.py <third_party_stub>)  # Install non-types dependencies

empty

(.venv3)$ python tests/get_external_dependencies.py <third_party_stub>  # List external dependencies for <third_party_stub>
(.venv3)$ python tests/get_external_dependencies.py <third_party_stub1> <third_party_stub2>  # List external dependencies for <third_party_stub1> and <third_party_stub2>
(.venv3)$ python tests/get_external_dependencies.py  # List external dependencies for all non stubs packages in typeshed
(.venv3)$ pip install $(python tests/get_external_dependencies.py <third_party_stub>)  # Install non-types dependencies

It doesn't outright break the syntax, if anything it highlights that you need to replace this part. It also correctly handles comments and inline commands.

Editors may have different implementations. This is in VSCode with popular markdown syntax highlight (and github-like previewer) that I use:
image

This is with plugins disabled:
image

You can see here that "shell" isn't naturally supported in the preview. (code syntax highlight has no difference). But I wouldn't use that as an argument.
Of course the exact look will depend on the editor's implementation.
In any case, having a language specifier here only seems better than no language specifier.

Another reason to use bash specifically, from a purely semantic point of view, is that the doc seems to assume all commands are to be run on linux, where afaik bash (or bash-like) is most often the default. (and bash-like code usually works in powershell on Windows)

Using bash by default, powershell for Windows-specific
Added missing start-of-line markers
Copy link
Member

@AlexWaygood AlexWaygood left a comment

Choose a reason for hiding this comment

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

Thanks!

@AlexWaygood AlexWaygood merged commit 0edcfa1 into python:main Jan 2, 2023
@Avasam Avasam deleted the specify-language-in-block-codes branch January 3, 2023 00:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants