contributing.rst: add instructions for creating virtualenv, update in…

…structions for running w/ coverage (#3036)

* add instructions for creating virtualenv, update instructions for running with coverage

* fixes after review

* okay now instructions actually work

docs/source/contributing.rst

@@ -176,6 +176,24 @@ This keeps us closer to the desired state where each open issue reflects some
 work that still needs to be done.
 
 
+Environment
+~~~~~~~~~~~
+We strongly suggest using a virtual environment for managing dependencies,
+for example with `venv <https://docs.python.org/3/library/venv.html>`__. So to
+set up your environment and install dependencies, you should run something like:
+
+.. code-block:: shell
+
+   cd path/to/trio/checkout/
+   python -m venv .venv # create virtual env in .venv
+   source .venv/bin/activate # activate it
+   pip install -e . # install trio, needed for pytest plugin
+   pip install -r test-requirements.txt # install test requirements
+
+you rarely need to recreate the virtual environment, but you need to re-activate it
+in future terminals. You might also need to re-install from test-requirements.txt if
+the versions in it get updated.
+
 .. _pull-request-tests:
 
 Tests
@@ -186,12 +204,11 @@ locally, you should run:
 
 .. code-block:: shell
 
-   cd path/to/trio/checkout/
-   pip install -r test-requirements.txt  # possibly using a virtualenv
-   pytest trio
+   source .venv/bin/activate # if not already activated
+   pytest src
 
 This doesn't try to be completely exhaustive – it only checks that
-things work on your machine, and it may skip some slow tests. But it's
+things work on your machine, and it will skip some slow tests. But it's
 a good way to quickly check that things seem to be working, and we'll
 automatically run the full test suite when your PR is submitted, so
 you'll have a chance to see and fix any remaining issues then.
@@ -211,8 +228,14 @@ it being merely hard to fix). For example:
 We use Codecov to track coverage, because it makes it easy to combine
 coverage from running in different configurations. Running coverage
 locally can be useful
-(``pytest --cov=PACKAGENAME --cov-report=html``), but don't be
-surprised if you get lower coverage than when looking at Codecov
+
+.. code-block:: shell
+
+   coverage run -m pytest
+   coverage combine
+   coverage report
+
+but don't be surprised if you get lower coverage than when looking at Codecov
 reports, because there are some lines that are only executed on
 Windows, or macOS, or PyPy, or CPython, or... you get the idea. After
 you create a PR, Codecov will automatically report back with the