Document development better, including the testrunner options and network resource usage.

Fixes #1349 and fixes #1402

docs/development.rst

@@ -2,32 +2,70 @@
  Development
 =============
 
+This document provides information about developing gevent itself,
+including information about running tests.
+
+More information is in the ``CONTRIBUTING.rst`` document in the root
+of the gevent repository.
+
 ..
     The contributor guide (CONTRIBUTING.rst) references this document.
 
     Things to include:
 
+    - Custom commands in ``setup.py``
     - Writing tests and the gevent test framework:
       - Avoiding hard test dependencies.
-    - Resource usage.
-    - Custom commands in ``setup.py``
+      - Resource usage.
+      - test files must be executable
+      - Maybe these things belong in a README in the gevent.tests directory?
+
+
+Getting Started
+===============
+
+Developing gevent requires being able to install gevent from source.
+See :doc:`installing_from_source` for general information about that.
+
+It is recommended to install the development copy of gevent in a
+`virtual environment <https://docs.python.org/3/tutorial/venv.html>`_;
+you can use the :mod:`venv` module distributed with Python 3, or
+`virtualenv <https://pypi.org/project/virtualenv/>`_, possibly with
+`virtualenvwrapper <https://pypi.org/project/virtualenvwrapper/>`_.
+
+You may want a different virtual environment for each Python
+implementation and version that you'll be working with. gevent
+includes a `tox <http://tox.readthedocs.org/>`_ configuration for
+automating the process of testing across multiple Python versions, but
+that can be slow.
 
+The rest of this document will assume working in an isolated virtual
+environment, but usually won't show that in the prompt. An example of
+creating a virtual environment is shown here::
 
+  $ python3 -m venv gevent-env
+  $ cd gevent-env
+  $ . bin/activate
+  (gevent-env) $
 
-To hack on gevent (using a virtualenv)::
 
-  $ git clone https://github.com/gevent/gevent.git
-  $ cd gevent
-  $ virtualenv env
-  $ source env/bin/activate
-  (env) $ pip install -r dev-requirements.txt
+To work on gevent, we'll need to get the source, install gevent's
+dependencies, including test dependencies, and install gevent as an
+`editable install
+<https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_
+using pip's `-e option` (also known as `development mode
+<https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_,
+this is mostly the same as running ``python setup.py develop``).
 
-.. note::
+Getting the source means cloning the git repository::
 
-   The notes above about installing from source apply here as well.
-   The ``dev-requirements.txt`` file takes care of the library
-   prerequisites (CFFI, Cython), but having a working C compiler that
-   can create Python extensions is up to you.
+  (gevent-env) $ git clone https://github.com/gevent/gevent.git
+  (gevent-env) $ cd gevent
+
+Installing gevent's dependencies, test dependencies, and gevent itself
+can be done in one line by installing the ``dev-requirements.txt`` file::
+
+  (gevent-env) $ pip install -r dev-requirements.txt
 
 .. warning::
 
@@ -37,17 +75,69 @@ To hack on gevent (using a virtualenv)::
 
 
 Running Tests
--------------
+=============
 
-There are a few different ways to run the tests. To simply run the
-tests on one version of Python during development, begin with the
-above instructions to install gevent in a virtual environment and then
-run::
+gevent has an extensive regression test suite, implemented using the
+standard :mod:`unittest` module. It uses a :mod:`custom testrunner
+<gevent.testing.testrunner>` that provides enhanced test isolation
+(important for monkey-patching), runs tests in parallel, and takes
+care of other gevent-specific quirks.
 
-  (env) $ python -mgevent.tests
+The test runner has a number of options:
 
 .. command-output:: python -mgevent.tests --help
 
+The simplest way to run all the tests is just to invoke the test
+runner, typically from the root of the source checkout::
+
+  (gevent-env) $ python -mgevent.tests
+  Running tests in parallel with concurrency 7
+  ...
+  Ran 3107 tests (skipped=333) in 132 files in 01:52
+
+You can also run an individual gevent test file using the test runner::
+
+
+  (gevent-env) $ python -m gevent.tests test__util.py
+  Running tests in parallel with concurrency 1
+  + /.../python -u -mgevent.tests.test__util
+  - /.../python -u -mgevent.tests.test__util [Ran 9 tests in 1.1s]
+
+  Longest-running tests:
+  1.1 seconds: /.../python -u -mgevent.tests.test__util
+
+  Ran 9 tests in 1 files in 1.1s
+
+
+Or you can run a monkey-patched standard library test::
+
+  (gevent-env) $ python -m gevent.tests.test___monkey_patching test_socket.py
+  Running tests in parallel with concurrency 1
+  + /.../python -u -W ignore -m gevent.testing.monkey_test test_socket.py
+  Running with patch_all(Event=False): test_socket.py
+  Added imports 1
+  Skipped testEmptyFileSend (1)
+  ...
+  Ran 555 tests in 23.042s
+
+  OK (skipped=172)
+  - /.../python -u -W ignore -m gevent.testing.monkey_test test_socket.py [took 26.7s]
+
+  Longest-running tests:
+  26.7 seconds: /.../python -u -W ignore -m gevent.testing.monkey_test test_socket.py
+
+  Ran 0 tests in 1 files in 00:27
+
+Environment Variables
+---------------------
+
+Some testrunner options have equivalent environment variables.
+Notably, ``--quiet`` is ``GEVENTTEST_QUIET`` and ``-u`` is
+``GEVENTTEST_USE_RESOURCES``.
+
+Using tox
+---------
+
 Before submitting a pull request, it's a good idea to run the tests
 across all supported versions of Python, and to check the code quality
 using prospector. This is what is done on Travis CI. Locally it
@@ -56,6 +146,12 @@ can be done using tox::
   pip install tox
   tox
 
+
+Measuring Code Coverage
+-----------------------
+
+This is done on CI so it's not often necessary to do locally.
+
 The testrunner accepts a ``--coverage`` argument to enable code
 coverage metrics through the `coverage.py`_ package. That would go
 something like this::
@@ -65,8 +161,23 @@ something like this::
   coverage html -i
   <open htmlcov/index.html>
 
+Limiting Resource Usage
+-----------------------
+
+gevent supports the standard library test suite's resources. All
+resources are enabled by default. Disabling resources disables the
+tests that use those resources. For example, to disable tests that
+access the external network (the Internet), disable the ``network``
+resource. There's an option for this::
+
+  $ python -m gevent.tests -u-network
+
+And an environment variable::
+
+  $ GEVENTTEST_USE_RESOURCES=-network python -m gevent.tests
+
 Continuous integration
-----------------------
+======================
 
 A test suite is run for every push and pull request submitted. Travis
 CI is used to test on Linux, and `AppVeyor`_ runs the builds on

docs/mytheme/static/basic.css_t

@@ -556,7 +556,7 @@ img.alignright, img.right {margin: 0 0 1em 1.5em;}
 /* Wrapper */
 #site-wrapper {
 	margin: 0 auto;
-	width: 920px;
+	width: 80%;
 }
 
 

src/gevent/events.py

@@ -438,6 +438,9 @@ class IGeventDidPatchBuiltinModulesEvent(IGeventDidPatchEvent):
     """
     Event emitted *after* the builtin modules have been patched.
 
+    If you're going to monkey-patch a third-party library, this is
+    usually the event to listen for.
+
     The values of the *source* and *target* attributes are undefined.
     """