diff --git a/docs/howto/windows.txt b/docs/howto/windows.txt index d624e13bff..9c1705f90a 100644 --- a/docs/howto/windows.txt +++ b/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 diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index e0369b5800..4cedb1ccf3 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/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 `__. Second, create and activate a virtual environment. If you're not familiar with how to do that, read our :doc:`contributing tutorial `. -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 `_ 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 `, the :ref:`documentation spelling checker `, and :ref:`code formatting `), 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 `. 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 ` 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=`` 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`. 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 ` 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 ` 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 diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt index e5ca34b8e6..2b115f6ce6 100644 --- a/docs/intro/contributing.txt +++ b/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 + ` and then use: + + .. code-block:: doscon + + ...\> workon djangodev __ https://virtualenvwrapper.readthedocs.io/en/latest/