Documentation - adopt consistent `sh` console code snippets (#9321)

README.md

@@ -58,7 +58,7 @@ To get started with using Wagtail, run the following in a virtual environment:
 
 ![Installing Wagtail](.github/install-animation.gif)
 
-```bash
+```sh
 pip install wagtail
 wagtail start mysite
 cd mysite

docs/advanced_topics/images/feature_detection.md

@@ -23,8 +23,8 @@ It includes a Python interface to OpenCV, as well as the statically-built OpenCV
 
 To install:
 
-```console
-$ pip install opencv-python
+```sh
+pip install opencv-python
 ```
 
 Depending on what else is installed on your system, this may be all that is required. On lighter-weight Linux systems, you may need to identify and install missing system libraries (for example, a slim version of Debian Stretch requires `libsm6 libxrender1 libxext6` to be installed with `apt`).
@@ -66,9 +66,9 @@ If you don't get an import error, installation has probably been successful.
 
 [Rustface](https://github.com/torchbox/rustface-py/) is Python library with prebuilt wheel files provided for Linux and macOS. Although implemented in Rust it is pip-installable:
 
-```console
-$ pip install wheel
-$ pip install rustface
+```sh
+pip install wheel
+pip install rustface
 ```
 
 #### Registering with Willow

docs/contributing/committing.md

@@ -46,7 +46,7 @@ If this is not possible because of the nature of the changes, it's acceptable
 to either squash into a commit or leave all commits unsquashed,
 depending on which will be more readable in the commit history.
 
-```console
+```sh
 # Get the latest commits from Wagtail
 git fetch upstream
 git checkout main
@@ -98,7 +98,7 @@ If the changes to be merged are small enough to be a single commit,
 amend this single commit with the additions to
 the `CHANGELOG.txt`, release notes, and contributors:
 
-```console
+```sh
 git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md
 git commit --amend --no-edit
 ```
@@ -107,7 +107,7 @@ If the changes do not fit in a single commit, make a new commit with the updates
 the `CHANGELOG.txt`, release notes, and contributors.
 The commit message should say `Release notes for #xxxx`:
 
-```console
+```sh
 git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md
 git commit -m 'Release notes for #xxxx'
 ```
@@ -116,7 +116,7 @@ git commit -m 'Release notes for #xxxx'
 
 The changes are ready to be pushed to `main` now.
 
-```console
+```sh
 # Check that everything looks OK
 git log upstream/main..main --oneline
 git push --dry-run upstream main
@@ -139,7 +139,7 @@ commits to the pull request branch of the contributor.
 
 Given that the contributor username is johndoe and his pull request branch is called foo:
 
-```console
+```sh
 git clone git@github.com:wagtail/wagtail.git
 cd wagtail
 git remote add johndoe git@github.com:johndoe/wagtail.git

docs/contributing/developing.md

@@ -21,27 +21,27 @@ You will also need to install the **libjpeg** and **zlib** libraries, if you hav
 
 Clone a copy of [the Wagtail codebase](https://github.com/wagtail/wagtail):
 
-```console
-$ git clone https://github.com/wagtail/wagtail.git
-$ cd wagtail
+```sh
+git clone https://github.com/wagtail/wagtail.git
+cd wagtail
 ```
 
 **With your preferred virtualenv activated,** install the Wagtail package in development mode with the included testing and documentation dependencies:
 
-```console
-$ pip install -e '.[testing,docs]' -U
+```sh
+pip install -e '.[testing,docs]' -U
 ```
 
 Install the tool chain for building static assets:
 
-```console
-$ npm ci
+```sh
+npm ci
 ```
 
 Compile the assets:
 
-```console
-$ npm run build
+```sh
+npm run build
 ```
 
 Any Wagtail sites you start up in this virtualenv will now run against this development instance of Wagtail. We recommend using the [Wagtail Bakery demo site](https://github.com/wagtail/bakerydemo/) as a basis for developing Wagtail. Keep in mind that the setup steps for a Wagtail site may include installing a release version of Wagtail, which will override the development version you've just set up. In this case, you should install the site before running the `pip install -e` step, or re-run that step after the site is installed.
@@ -52,8 +52,8 @@ Any Wagtail sites you start up in this virtualenv will now run against this deve
 
 From the root of the Wagtail codebase, run the following command to run all the Python tests:
 
-```console
-$ python runtests.py
+```sh
+python runtests.py
 ```
 
 ### Running only some of the tests
@@ -62,34 +62,34 @@ At the time of writing, Wagtail has well over 2500 tests, which takes a while to
 run. You can run tests for only one part of Wagtail by passing in the path as
 an argument to `runtests.py` or `tox`:
 
-```console
+```sh
 # Running in the current environment
-$ python runtests.py wagtail
+python runtests.py wagtail
 
 # Running in a specified Tox environment
-$ tox -e py39-dj32-sqlite-noelasticsearch wagtail
+tox -e py39-dj32-sqlite-noelasticsearch wagtail
 
 # See a list of available Tox environments
-$ tox -l
+tox -l
 ```
 
 You can also run tests for individual TestCases by passing in the path as
 an argument to `runtests.py`
 
-```console
+```sh
 # Running in the current environment
-$ python runtests.py wagtail.tests.test_blocks.TestIntegerBlock
+python runtests.py wagtail.tests.test_blocks.TestIntegerBlock
 
 # Running in a specified Tox environment
-$ tox -e py39-dj32-sqlite-noelasticsearch wagtail.tests.test_blocks.TestIntegerBlock
+tox -e py39-dj32-sqlite-noelasticsearch wagtail.tests.test_blocks.TestIntegerBlock
 ```
 
 ### Running migrations for the test app models
 
 You can create migrations for the test app by running the following from the Wagtail root.
 
-```console
-$ django-admin makemigrations --settings=wagtail.test.settings
+```sh
+django-admin makemigrations --settings=wagtail.test.settings
 ```
 
 ### Testing against PostgreSQL
@@ -101,8 +101,8 @@ In order to run these tests, you must install the required modules for PostgreSQ
 By default, Wagtail tests against SQLite. You can switch to using PostgreSQL by
 using the `--postgres` argument:
 
-```console
-$ python runtests.py --postgres
+```sh
+python runtests.py --postgres
 ```
 
 If you need to use a different user, password, host or port, use the `PGUSER`, `PGPASSWORD`, `PGHOST` and `PGPORT` environment variables respectively.
@@ -116,8 +116,8 @@ In order to run these tests, you must install the required client libraries and
 If you need to test against a different database, set the `DATABASE_ENGINE`
 environment variable to the name of the Django database backend to test against:
 
-```console
-$ DATABASE_ENGINE=django.db.backends.mysql python runtests.py
+```sh
+DATABASE_ENGINE=django.db.backends.mysql python runtests.py
 ```
 
 This will create a new database called `test_wagtail` in MySQL and run
@@ -139,8 +139,8 @@ It is also possible to set `DATABASE_DRIVER`, which corresponds to the `driver`
 You can test Wagtail against Elasticsearch by passing the `--elasticsearch`
 argument to `runtests.py`:
 
-```console
-$ python runtests.py --elasticsearch
+```sh
+python runtests.py --elasticsearch
 ```
 
 Wagtail will attempt to connect to a local instance of Elasticsearch
@@ -149,32 +149,32 @@ Wagtail will attempt to connect to a local instance of Elasticsearch
 If your Elasticsearch instance is located somewhere else, you can set the
 `ELASTICSEARCH_URL` environment variable to point to its location:
 
-```console
-$ ELASTICSEARCH_URL=http://my-elasticsearch-instance:9200 python runtests.py --elasticsearch
+```sh
+ELASTICSEARCH_URL=http://my-elasticsearch-instance:9200 python runtests.py --elasticsearch
 ```
 
 ### Unit tests for JavaScript
 
 We use [Jest](https://jestjs.io/) for unit tests of client-side business logic or UI components. From the root of the Wagtail codebase, run the following command to run all the front-end unit tests:
 
-```console
-$ npm run test:unit
+```sh
+npm run test:unit
 ```
 
 ### Integration tests
 
 Our end-to-end browser testing suite also uses [Jest](https://jestjs.io/), combined with [Puppeteer](https://pptr.dev/). We set this up to be installed separately so as not to increase the installation size of the existing Node tooling. To run the tests, you will need to install the dependencies and, in a separate terminal, run the test suite’s Django development server:
 
-```console
-$ export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
+```sh
+export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
 # Assumes the current environment contains a valid installation of Wagtail for local development.
-$ ./wagtail/test/manage.py migrate
-$ ./wagtail/test/manage.py createcachetable
-$ DJANGO_SUPERUSER_EMAIL=admin@example.com DJANGO_SUPERUSER_USERNAME=admin DJANGO_SUPERUSER_PASSWORD=changeme ./wagtail/test/manage.py createsuperuser --noinput
-$ ./wagtail/test/manage.py runserver 0:8000
+./wagtail/test/manage.py migrate
+./wagtail/test/manage.py createcachetable
+DJANGO_SUPERUSER_EMAIL=admin@example.com DJANGO_SUPERUSER_USERNAME=admin DJANGO_SUPERUSER_PASSWORD=changeme ./wagtail/test/manage.py createsuperuser --noinput
+./wagtail/test/manage.py runserver 0:8000
 # In a separate terminal:
-$ npm --prefix client/tests/integration install
-$ npm run test:integration
+npm --prefix client/tests/integration install
+npm run test:integration
 ```
 
 Integration tests target `http://localhost:8000` by default. Use the `TEST_ORIGIN` environment variable to use a different port, or test a remote Wagtail instance: `TEST_ORIGIN=http://localhost:9000 npm run test:integration`.
@@ -244,28 +244,28 @@ All static assets such as JavaScript, CSS, images, and fonts for the Wagtail adm
 
 To compile the assets, run:
 
-```console
-$ npm run build
+```sh
+npm run build
 ```
 
 This must be done after every change to the source files. To watch the source files for changes and then automatically recompile the assets, run:
 
-```console
-$ npm start
+```sh
+npm start
 ```
 
 ## Using the pattern library
 
 Wagtail’s UI component library is built with [Storybook](https://storybook.js.org/) and [django-pattern-library](https://github.com/torchbox/django-pattern-library). To run it locally,
 
-```console
-$ export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
+```sh
+export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
 # Assumes the current environment contains a valid installation of Wagtail for local development.
-$ ./wagtail/test/manage.py migrate
-$ ./wagtail/test/manage.py createcachetable
-$ ./wagtail/test/manage.py runserver 0:8000
+./wagtail/test/manage.py migrate
+./wagtail/test/manage.py createcachetable
+./wagtail/test/manage.py runserver 0:8000
 # In a separate terminal:
-$ npm run storybook
+npm run storybook
 ```
 
 The last command will start Storybook at `http://localhost:6006/`. It will proxy specific requests to Django at `http://localhost:8000` by default. Use the `TEST_ORIGIN` environment variable to use a different port for Django: `TEST_ORIGIN=http://localhost:9000 npm run storybook`.
@@ -274,15 +274,15 @@ The last command will start Storybook at `http://localhost:6006/`. It will proxy
 
 The Wagtail documentation is built by Sphinx. To install Sphinx and compile the documentation, run:
 
-```console
-$ cd /path/to/wagtail
+```sh
+cd /path/to/wagtail
 # Install the documentation dependencies
-$ pip install -e .[docs]
+pip install -e .[docs]
 # or if using zsh as your shell:
 #    pip install -e '.[docs]' -U
 # Compile the docs
-$ cd docs/
-$ make html
+cd docs/
+make html
 ```
 
 The compiled documentation will now be in `docs/_build/html`.
@@ -290,9 +290,9 @@ Open this directory in a web browser to see it.
 Python comes with a module that makes it very easy to preview static files in a web browser.
 To start this simple server, run the following commands:
 
-```console
-$ cd docs/_build/html/
-$ python -m http.server 8080
+```sh
+cd docs/_build/html/
+python -m http.server 8080
 ```
 
 Now you can open <http://localhost:8080/> in your web browser to see the compiled documentation.
@@ -301,26 +301,26 @@ Sphinx caches the built documentation to speed up subsequent compilations.
 Unfortunately, this cache also hides any warnings thrown by unmodified documentation source files.
 To clear the built HTML and start fresh, so you can see all warnings thrown when building the documentation, run:
 
-```console
-$ cd docs/
-$ make clean
-$ make html
+```sh
+cd docs/
+make clean
+make html
 ```
 
 Wagtail also provides a way for documentation to be compiled automatically on each change.
 To do this, you can run the following command to see the changes automatically at `localhost:4000`:
 
-```console
-$ cd docs/
-$ make livehtml
+```sh
+cd docs/
+make livehtml
 ```
 
 ## Automatically lint and code format on commits
 
 [pre-commit](https://pre-commit.com/) is configured to automatically run code linting and formatting checks with every commit. To install pre-commit into your git hooks run:
 
-```console
-$ pre-commit install
+```sh
+pre-commit install
 ```
 
 pre-commit should now run on every commit you make.

docs/contributing/documentation_guidelines.md

@@ -72,7 +72,7 @@ Use **bold** and _italic_ sparingly, inline `code` when relevant.
 
 ### Code blocks
 
-Make sure to include the correct language code for syntax highlighting, and to format your code according to our coding guidelines. Frequently used: `python`, `css`, `html`, `html+django`, `javascript`, `console`.
+Make sure to include the correct language code for syntax highlighting, and to format your code according to our coding guidelines. Frequently used: `python`, `css`, `html`, `html+django`, `javascript`, `sh`.
 
     ```python
     INSTALLED_APPS = [
@@ -82,6 +82,26 @@ Make sure to include the correct language code for syntax highlighting, and to f
     ]
     ```
 
+#### When using console (terminal) code blocks
+
+```{note}
+`$` or `>` prompts are not needed, this makes it harder to copy and paste the lines and can be difficult to consistently add in every single code snippet.
+```
+
+Use `sh` as it has better support for comment and code syntax highlighting in MyST's parser, plus is more compatible with GitHub and VSCode.
+
+    ```sh
+    # some comment
+    some command
+    ```
+
+Use `doscon` (DOS Console) only if explicitly calling out Windows commands alongside their bash equivalent.
+
+    ```doscon
+    # some comment
+    some command
+    ```
+
 ### Links
 
 Links are fundamental in documentation. Use internal links to tie your content to other docs, and external links as needed. Pick relevant text for links, so readers know where they will land.

docs/getting_started/index.md

@@ -22,7 +22,7 @@
 Run the following commands in a virtual environment of your choice:
 
 ```sh
-$ pip install wagtail
+pip install wagtail
 ```
 
 (Installing wagtail outside a virtual environment may require `sudo`. sudo is a program to run other programs with the security privileges of another user, by default the superuser)
@@ -30,7 +30,7 @@ $ pip install wagtail
 Once installed, Wagtail provides a command similar to Django\'s `django-admin startproject` to generate a new site/project:
 
 ```sh
-$ wagtail start mysite
+wagtail start mysite
 ```
 
 This will create a new folder `mysite`, based on a template containing everything you need to get started.
@@ -40,10 +40,10 @@ More information on that template is available in
 Inside your `mysite` folder, run the setup steps necessary for any Django project:
 
 ```sh
-$ pip install -r requirements.txt
-$ python manage.py migrate
-$ python manage.py createsuperuser
-$ python manage.py runserver
+pip install -r requirements.txt
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py runserver
 ```
 
 Your site is now accessible at `http://localhost:8000`, with the admin backend available at `http://localhost:8000/admin/`.

docs/getting_started/integrating_into_django.md

@@ -5,7 +5,7 @@ Wagtail provides the `wagtail start` command and project template to get you sta
 Wagtail is currently compatible with Django 3.2, 4.0 and 4.1. First, install the `wagtail` package from PyPI:
 
 ```sh
-$ pip install wagtail
+pip install wagtail
 ```
 
 or add the package to your existing requirements file. This will also install the **Pillow** library as a dependency, which requires libjpeg and zlib - see Pillow's [platform-specific installation instructions](https://pillow.readthedocs.io/en/stable/installation.html#external-libraries).

docs/getting_started/tutorial.md

@@ -13,8 +13,8 @@ Wagtail supports Python 3.7, 3.8, 3.9 and 3.10.
 
 To check whether you have an appropriate version of Python 3:
 
-```console
-$ python3 --version
+```sh
+python3 --version
 ```
 
 If this does not return a version number or returns a version lower than 3.7, you will need to [install Python 3](https://www.python.org/downloads/).
@@ -33,21 +33,20 @@ This tutorial uses [`venv`](https://docs.python.org/3/tutorial/venv.html), which
 **On Windows** (cmd.exe):
 
 ```doscon
-> python3 -m venv mysite\env
-> mysite\env\Scripts\activate.bat
-
-Or:
-
-> mysite\env\Scripts\activate
+python3 -m venv mysite\env
+mysite\env\Scripts\activate.bat
+# or:
+mysite\env\Scripts\activate
 ```
 
 **On GNU/Linux or MacOS** (bash):
 
-```console
-$ python3 -m venv mysite/env
-$ source mysite/env/bin/activate
+```sh
+python3 -m venv mysite/env
+source mysite/env/bin/activate
 ```
 
+
 **For other shells** see the [`venv` documentation](https://docs.python.org/3/library/venv.html).
 
 ```{note}
@@ -59,8 +58,8 @@ The `env` directory inside of it should be excluded from any version control.
 
 Use pip, which is packaged with Python, to install Wagtail and its dependencies:
 
-```console
-$ pip install wagtail
+```sh
+pip install wagtail
 ```
 
 ### Generate your site
@@ -73,8 +72,8 @@ and a sample "search" app.
 
 Because the folder `mysite` was already created by `venv`, run `wagtail start` with an additional argument to specify the destination directory:
 
-```console
-$ wagtail start mysite mysite
+```sh
+wagtail start mysite mysite
 ```
 
 ```{note}
@@ -83,9 +82,9 @@ Generally, in Wagtail, each page type, or content type, is represented by a sing
 
 ### Install project dependencies
 
-```console
-$ cd mysite
-$ pip install -r requirements.txt
+```sh
+cd mysite
+pip install -r requirements.txt
 ```
 
 This ensures that you have the relevant versions of Wagtail, Django, and any other dependencies for the project you have just created.
@@ -95,24 +94,24 @@ The `requirements.txt` file contains all the dependencies needed in order to run
 
 If you haven't updated the project settings, this will be a SQLite database file in the project directory.
 
-```console
-$ python manage.py migrate
+```sh
+python manage.py migrate
 ```
 
 This command ensures that the tables in your database are matched to the models in your project. Every time you alter your model (for example you may add a field to a model) you will need to run this command in order to update the database.
 
 ### Create an admin user
 
-```console
-$ python manage.py createsuperuser
+```sh
+python manage.py createsuperuser
 ```
 
 When logged into the admin site, a superuser has full permissions and is able to view/create/manage the database.
 
 ### Start the server
 
-```console
-$ python manage.py runserver
+```sh
+python manage.py runserver
 ```
 
 If everything worked, <http://127.0.0.1:8000> will show you a welcome page:

docs/reference/contrib/redirects.md

@@ -74,8 +74,8 @@ WAGTAILREDIRECTS_AUTO_CREATE = False
 
 ### `import_redirects`
 
-```console
-$ ./manage.py import_redirects
+```sh
+./manage.py import_redirects
 ```
 
 This command imports and creates redirects from a file supplied by the user.

docs/reference/management_commands.md

@@ -11,8 +11,8 @@ This command has been renamed from `publish_scheduled_pages` to `publish_schedul
 The `publish_scheduled_pages` command is still available as an alias, but it is recommended to update your configuration to run the `publish_scheduled` command instead.
 ```
 
-```console
-$ ./manage.py publish_scheduled
+```sh
+./manage.py publish_scheduled
 ```
 
 This command publishes, updates or unpublishes objects that have had these actions scheduled by an editor. We recommend running this command once an hour.
@@ -21,8 +21,8 @@ This command publishes, updates or unpublishes objects that have had these actio
 
 ## fixtree
 
-```console
-$ ./manage.py fixtree
+```sh
+./manage.py fixtree
 ```
 
 This command scans for errors in your database and attempts to fix any issues it finds.
@@ -31,8 +31,8 @@ This command scans for errors in your database and attempts to fix any issues it
 
 ## move_pages
 
-```console
-$ manage.py move_pages from to
+```sh
+manage.py move_pages from to
 ```
 
 This command moves a selection of pages from one section of the tree to another.
@@ -49,8 +49,8 @@ Options:
 
 ## purge_revisions
 
-```console
-$ manage.py purge_revisions [--days=<number of days>]
+```sh
+manage.py purge_revisions [--days=<number of days>]
 ```
 
 This command deletes old page revisions which are not in moderation, live, approved to go live, or the latest
@@ -61,8 +61,8 @@ days will be deleted.
 
 ## update_index
 
-```console
-$ ./manage.py update_index [--backend <backend name>]
+```sh
+./manage.py update_index [--backend <backend name>]
 ```
 
 This command rebuilds the search index from scratch.
@@ -82,8 +82,8 @@ If you have multiple backends and would only like to update one of them, you can
 
 For example, to update just the default backend:
 
-```console
-$ python manage.py update_index --backend default
+```sh
+python manage.py update_index --backend default
 ```
 
 The `--chunk_size` option can be used to set the size of chunks that are indexed at a time. This defaults to
@@ -93,8 +93,8 @@ The `--chunk_size` option can be used to set the size of chunks that are indexed
 
 You can prevent the `update_index` command from indexing any data by using the `--schema-only` option:
 
-```console
-$ python manage.py update_index --schema-only
+```sh
+python manage.py update_index --schema-only
 ```
 
 (wagtail_update_index)=
@@ -107,16 +107,16 @@ An alias for the `update_index` command that can be used when another installed
 
 ## rebuild_references_index
 
-```console
-$ ./manage.py rebuild_references_index
+```sh
+./manage.py rebuild_references_index
 ```
 
 This command populates the table that tracks cross-references between objects, used for the usage reports on images, documents and snippets. This table is updated automatically saving objects, but it is recommended to run this command periodically to ensure that the data remains consistent.
 
 ## search_garbage_collect
 
-```console
-$ ./manage.py search_garbage_collect
+```sh
+./manage.py search_garbage_collect
 ```
 
 Wagtail keeps a log of search queries that are popular on your website. On high traffic websites, this log may get big and you may want to clean out old search queries. This command cleans out all search query logs that are more than one week old (or a number of days configurable through the [`WAGTAILSEARCH_HITS_MAX_AGE`](wagtailsearch_hits_max_age) setting).
@@ -125,8 +125,8 @@ Wagtail keeps a log of search queries that are popular on your website. On high
 
 ## wagtail_update_image_renditions
 
-```console
-$ ./manage.py wagtail_update_image_renditions
+```sh
+./manage.py wagtail_update_image_renditions
 ```
 
 This command provides the ability to regenerate image renditions.

docs/reference/project_template.md

@@ -83,7 +83,7 @@ Location: `/mysite/Dockerfile`
 
 Contains configuration for building and deploying the site as a [Docker](https://docs.docker.com/) container. To build and use the Docker image for your project, run:
 
-```console
+```sh
 docker build -t mysite .
 docker run -p 8000:8000 mysite
 ```

docs/releases/3.0.md

@@ -144,7 +144,7 @@ Various modules of Wagtail have been reorganised, and imports should be updated
 
 These changes can be applied automatically to your project codebase by running the following commands from the project root:
 
-```console
+```sh
 wagtail updatemodulepaths --list  # list the files to be changed without updating them
 wagtail updatemodulepaths --diff  # show the changes to be made, without updating files
 wagtail updatemodulepaths  # actually update the files

docs/topics/images.md

@@ -392,8 +392,8 @@ Note that this won't affect any previously generated images so you may want to d
 
 You can also directly use the image management command from the console for regenerating the renditions:
 
-```console
-$ ./manage.py wagtail_update_image_renditions --purge
+```sh
+./manage.py wagtail_update_image_renditions --purge
 ```
 
 You can read more about this command from [](wagtail_update_image_renditions)