Fixed #30387 -- Enhanced docs CLI examples in Unit tests and Install Django on Windows.

Follow up to 37c17846ad6b02c6dca72e8087a279cca04a0c27.

docs/howto/windows.txt

@@ -2,6 +2,8 @@
 How to install Django on Windows
 ================================
 
+.. highlight:: doscon
+
 This document will guide you through installing Python 3.7 and Django on
 Windows. It also provides instructions for installing `virtualenv`_ and
 `virtualenvwrapper`_, which make it easier to work on Python projects. This is
@@ -21,13 +23,18 @@ machine. At the time of writing, Python 3.7 is the latest version.
 
 To install Python on your machine go to https://python.org/downloads/. The
 website should offer you a download button for the latest Python version.
-Download the executable installer and run it. Check the box next to ``Add
-Python 3.7 to PATH`` and then click ``Install Now``.
+Download the executable installer and run it. Check the boxes next to ``Install
+launcher for all users (recommended)`` and ``Add Python 3.7 to PATH`` then
+click ``Install Now``.
 
 After installation, open the command prompt and check that the Python version
 matches the version you installed by executing::
 
-    python --version
+    ...\> py --version
+
+.. seealso::
+
+    For more details, see :doc:`python:using/windows` documentation.
 
 About ``pip``
 =============
@@ -42,6 +49,8 @@ get-pip.py`` instructions.
 
 .. _pip: https://pypi.org/project/pip/
 
+.. _virtualenvwrapper-win:
+
 Install ``virtualenv`` and ``virtualenvwrapper``
 ================================================
 
@@ -50,17 +59,17 @@ each Django project you create. While not mandatory, this is considered a best
 practice and will save you time in the future when you're ready to deploy your
 project. Simply type::
 
-    python -m pip install virtualenvwrapper-win
+    ...\> py -m pip install virtualenvwrapper-win
 
 Then create a virtual environment for your project::
 
-    mkvirtualenv myproject
+    ...\> mkvirtualenv myproject
 
 The virtual environment will be activated automatically and you'll see
 "(myproject)" next to the command prompt to designate that. If you start a new
 command prompt, you'll need to activate the environment again using::
 
-    workon myproject
+    ...\> workon myproject
 
 .. _virtualenv: https://pypi.org/project/virtualenv/
 .. _virtualenvwrapper: https://pypi.org/project/virtualenvwrapper-win/
@@ -73,7 +82,7 @@ Django can be installed easily using ``pip`` within your virtual environment.
 In the command prompt, ensure your virtual environment is active, and execute
 the following command::
 
-    python -m pip install django
+    ...\> py -m pip install Django
 
 This will download and install the latest Django release.
 
@@ -92,9 +101,9 @@ Common pitfalls
   running Python scripts in ``PATH``. This usually occurs when there is more
   than one Python version installed.
 
-* If you are connecting to the internet behind a proxy, there might be problem
-  in running the command ``python -m pip install django``. Set the environment
+* If you are connecting to the internet behind a proxy, there might be problems
+  in running the command ``py -m pip install Django``. Set the environment
   variables for proxy configuration in the command prompt as follows::
 
-    set http_proxy=http://username:password@proxyserver:proxyport
-    set https_proxy=https://username:password@proxyserver:proxyport
+    ...\> set http_proxy=http://username:password@proxyserver:proxyport
+    ...\> set https_proxy=https://username:password@proxyserver:proxyport

docs/internals/contributing/writing-code/unit-tests.txt

@@ -2,8 +2,6 @@
 Unit tests
 ==========
 
-.. highlight:: console
-
 Django comes with a test suite of its own, in the ``tests`` directory of the
 code base. It's our policy to make sure all tests pass at all times.
 
@@ -26,7 +24,9 @@ First, `fork Django on GitHub <https://github.com/django/django/fork>`__.
 Second, create and activate a virtual environment. If you're not familiar with
 how to do that, read our :doc:`contributing tutorial </intro/contributing>`.
 
-Next, clone your fork, install some requirements, and run the tests::
+Next, clone your fork, install some requirements, and run the tests:
+
+.. console::
 
    $ git clone git@github.com:YourGitHubName/django.git django-repo
    $ cd django-repo/tests
@@ -50,11 +50,6 @@ settings module that uses the SQLite database. See
 :ref:`running-unit-tests-settings` to learn how to use a different settings
 module to run the tests with a different database.
 
-.. admonition:: Windows users
-
-    We recommend something like `Git Bash <https://msysgit.github.io/>`_ to run
-    the tests using the above approach.
-
 Having problems? See :ref:`troubleshooting-unit-tests` for some common issues.
 
 Running tests using ``tox``
@@ -66,7 +61,9 @@ checks that our build server performs on pull requests. To run the unit tests
 and other checks (such as :ref:`import sorting <coding-style-imports>`, the
 :ref:`documentation spelling checker <documentation-spelling-check>`, and
 :ref:`code formatting <coding-style-python>`), install and run the ``tox``
-command from any place in the Django source tree::
+command from any place in the Django source tree:
+
+.. console::
 
     $ python -m pip install tox
     $ tox
@@ -75,7 +72,9 @@ By default, ``tox`` runs the test suite with the bundled test settings file for
 SQLite, ``flake8``, ``isort``, and the documentation spelling checker. In
 addition to the system dependencies noted elsewhere in this documentation,
 the command ``python3`` must be on your path and linked to the appropriate
-version of Python. A list of default environments can be seen as follows::
+version of Python. A list of default environments can be seen as follows:
+
+.. console::
 
     $ tox -l
     py3
@@ -91,7 +90,9 @@ for other versions of Python and other database backends. Since Django's test
 suite doesn't bundle a settings file for database backends other than SQLite,
 however, you must :ref:`create and provide your own test settings
 <running-unit-tests-settings>`. For example, to run the tests on Python 3.7
-using PostgreSQL::
+using PostgreSQL:
+
+.. console::
 
     $ tox -e py37-postgres -- --settings=my_postgres_settings
 
@@ -105,10 +106,19 @@ The remainder of this documentation shows commands for running tests without
 ``tox`` by prefixing the argument list with ``--``, as above.
 
 Tox also respects the ``DJANGO_SETTINGS_MODULE`` environment variable, if set.
-For example, the following is equivalent to the command above::
+For example, the following is equivalent to the command above:
+
+.. code-block:: console
 
     $ DJANGO_SETTINGS_MODULE=my_postgres_settings tox -e py35-postgres
 
+Windows users should use:
+
+.. code-block:: doscon
+
+    ...\> set DJANGO_SETTINGS_MODULE=my_postgres_settings
+    ...\> tox -e py35-postgres
+
 Running the JavaScript tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -116,7 +126,9 @@ Django includes a set of :ref:`JavaScript unit tests <javascript-tests>` for
 functions in certain contrib apps. The JavaScript tests aren't run by default
 using ``tox`` because they require `Node.js` to be installed and aren't
 necessary for the majority of patches. To run the JavaScript tests using
-``tox``::
+``tox``:
+
+.. console::
 
     $ tox -e javascript
 
@@ -178,7 +190,9 @@ tests by appending the names of the test modules to ``runtests.py`` on the
 command line.
 
 For example, if you'd like to run tests only for generic relations and
-internationalization, type::
+internationalization, type:
+
+.. console::
 
    $ ./runtests.py --settings=path.to.settings generic_relations i18n
 
@@ -187,11 +201,15 @@ directory name there is the name of a test.
 
 If you just want to run a particular class of tests, you can specify a list of
 paths to individual test classes. For example, to run the ``TranslationTests``
-of the ``i18n`` module, type::
+of the ``i18n`` module, type:
+
+.. console::
 
    $ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests
 
-Going beyond that, you can specify an individual test method like this::
+Going beyond that, you can specify an individual test method like this:
+
+.. console::
 
    $ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects
 
@@ -201,7 +219,9 @@ Running the Selenium tests
 Some tests require Selenium and a Web browser. To run these tests, you must
 install the selenium_ package and run the tests with the
 ``--selenium=<BROWSERS>`` option. For example, if you have Firefox and Google
-Chrome installed::
+Chrome installed:
+
+.. console::
 
    $ ./runtests.py --selenium=firefox,chrome
 
@@ -238,7 +258,9 @@ dependencies:
 
 You can find these dependencies in `pip requirements files`_ inside the
 ``tests/requirements`` directory of the Django source tree and install them
-like so::
+like so:
+
+.. console::
 
    $ python -m pip install -r tests/requirements/py3.txt
 
@@ -288,11 +310,15 @@ that need additional tests. The coverage tool installation and use is described
 in :ref:`testing code coverage<topics-testing-code-coverage>`.
 
 Coverage should be run in a single process to obtain accurate statistics. To
-run coverage on the Django test suite using the standard test settings::
+run coverage on the Django test suite using the standard test settings:
+
+.. console::
 
    $ coverage run ./runtests.py --settings=test_sqlite --parallel=1
 
-After running coverage, generate the html report by running::
+After running coverage, generate the html report by running:
+
+.. console::
 
    $ coverage html
 
@@ -321,12 +347,16 @@ Many test failures with ``UnicodeEncodeError``
 If the ``locales`` package is not installed, some tests will fail with a
 ``UnicodeEncodeError``.
 
-You can resolve this on Debian-based systems, for example, by running::
+You can resolve this on Debian-based systems, for example, by running:
+
+.. code-block:: console
 
     $ apt-get install locales
     $ dpkg-reconfigure locales
 
-You can resolve this for macOS systems by configuring your shell's locale::
+You can resolve this for macOS systems by configuring your shell's locale:
+
+.. code-block:: console
 
     $ export LANG="en_US.UTF-8"
     $ export LC_ALL="en_US.UTF-8"
@@ -347,7 +377,9 @@ it possible to identify a small number of tests that may be related to the
 failure.
 
 For example, suppose that the failing test that works on its own is
-``ModelTest.test_eq``, then using::
+``ModelTest.test_eq``, then using:
+
+.. console::
 
     $ ./runtests.py --bisect basic.tests.ModelTest.test_eq
 
@@ -361,7 +393,9 @@ failing tests is minimized.
 
 The ``--pair`` option runs the given test alongside every other test from the
 suite, letting you check if another test has side-effects that cause the
-failure. So::
+failure. So:
+
+.. console::
 
     $ ./runtests.py --pair basic.tests.ModelTest.test_eq
 
@@ -370,13 +404,17 @@ will pair ``test_eq`` with every test label.
 With both ``--bisect`` and ``--pair``, if you already suspect which cases
 might be responsible for the failure, you may limit tests to be cross-analyzed
 by :ref:`specifying further test labels <runtests-specifying-labels>` after
-the first one::
+the first one:
+
+.. console::
 
     $ ./runtests.py --pair basic.tests.ModelTest.test_eq queries transactions
 
 You can also try running any set of tests in reverse using the ``--reverse``
 option in order to verify that executing tests in a different order does not
-cause any trouble::
+cause any trouble:
+
+.. console::
 
     $ ./runtests.py basic --reverse
 
@@ -385,7 +423,9 @@ Seeing the SQL queries run during a test
 
 If you wish to examine the SQL being run in failing tests, you can turn on
 :ref:`SQL logging <django-db-logger>` using the ``--debug-sql`` option. If you
-combine this with ``--verbosity=2``, all SQL queries will be output::
+combine this with ``--verbosity=2``, all SQL queries will be output:
+
+.. console::
 
     $ ./runtests.py basic --debug-sql
 
@@ -394,7 +434,9 @@ Seeing the full traceback of a test failure
 
 By default tests are run in parallel with one process per core. When the tests
 are run in parallel, however, you'll only see a truncated traceback for any
-test failures. You can adjust this behavior with the ``--parallel`` option::
+test failures. You can adjust this behavior with the ``--parallel`` option:
+
+.. console::
 
     $ ./runtests.py basic --parallel=1
 

docs/intro/contributing.txt

@@ -150,6 +150,10 @@ If the ``source`` command is not available, you can try using a dot instead:
 
     $ . ~/.virtualenvs/djangodev/bin/activate
 
+You have to activate the virtual environment whenever you open a new
+terminal window. virtualenvwrapper__ is a useful tool for making this
+more convenient.
+
 .. admonition:: For Windows users
 
     To activate your virtual environment on Windows, run:
@@ -158,9 +162,12 @@ If the ``source`` command is not available, you can try using a dot instead:
 
         ...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
 
-You have to activate the virtual environment whenever you open a new
-terminal window. virtualenvwrapper__ is a useful tool for making this
-more convenient.
+    or you can install :ref:`a Windows version of virtualenvwrapper
+    <virtualenvwrapper-win>` and then use:
+
+    .. code-block:: doscon
+
+        ...\> workon djangodev
 
 __ https://virtualenvwrapper.readthedocs.io/en/latest/