Centralize installation documents. Fixes #1210. [skip ci]

I checked with restview --long --pypi and the long description still
renders nicely, as do the pages created by sphinx

I thought the use of .. include:: would make README.rst still render
with all its contents, but sadly github doesn't enable
that (github/markup#172)

README.rst

@@ -2,155 +2,26 @@
  gevent
 ========
 
-gevent_ is a coroutine-based Python networking library.
-
-Features include:
-
-* Fast event loop based on libev_ or libuv_.
-* Lightweight execution units based on greenlet_.
-* Familiar API that re-uses concepts from the Python standard library.
-* Cooperative sockets with SSL support.
-* DNS queries performed through c-ares_ or a threadpool.
-* Ability to use standard library and 3rd party modules written for standard blocking sockets
-
-gevent is `inspired by eventlet`_ but features more consistent API,
-simpler implementation and better performance. Read why others `use
-gevent`_ and check out the list of the `open source projects based on
-gevent`_.
-
-gevent was written by `Denis Bilenko <http://denisbilenko.com/>`_.
-
-Since version 1.1, gevent is maintained by `NextThought
-<https://nextthought.com>`_ with help from the `contributors
-<https://github.com/gevent/gevent/graphs/contributors>`_ and is
-licensed under the MIT license.
-
-See `what's new`_ in the latest major release.
-
-Check out the detailed changelog_ for this version.
-
-Get gevent
-==========
-
-gevent runs on Python >= 2.7, Python >= 3.4, or PyPy >= 5.5 (including
-PyPy2 and PyPy3). On all platforms, installing setuptools is required
-(this is done automatically if working in a virtual environment).
-
-You can use pip to install gevent::
-
-    pip install gevent
-
-.. tip:: You need Pip 8.0 or later to install the binary wheels.
-
-.. tip:: You need to install from source, not the manylinux wheels, to
-         use the libuv backend.
-
-.. tip::
-
-   gevent uses :pep:`496` environment markers in ``setup.py``.
-   Consequently, you'll need a version of setuptools newer than 25
-   (mid 2016) to install gevent from source. Older versions of pipenv
-   may also `have issues installing gevent for this reason
-   <https://github.com/pypa/pipenv/issues/2113>`_.
-
-Download the latest release from `Python Package Index`_ or clone `the repository`_.
-
-Read the documentation online at http://www.gevent.org. Additional
-installation information can be found `here <http://www.gevent.org/intro.html#installation-and-requirements>`_.
-
-Post feedback and issues on the `bug tracker`_, `mailing list`_, blog_
-and `twitter (@gevent)`_.
-
-
-Development
-===========
-
-To install the latest development version::
-
-  pip install setuptools cffi 'cython>=0.27' git+git://github.com/gevent/gevent.git#egg=gevent
-
-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
-
-.. note::
-
-   You must have a C compiler, Cython, and the Python development headers
-   installed to build a checkout. Installing CFFI on CPython (it's
-   standard on PyPy) allows building the CFFI backends for testing, and
-   tox is the command used to test multiple versions of Python.
-
-
-Running Tests
--------------
-
-There are a few different ways to run the tests. To simply run the
-tests on one version of Python during development, try this::
-
-  (env) $ pip install -e .
-  (env) $ cd src/greentest
-  (env) $ python ./testrunner.py
-
-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
-can be done using tox::
-
-  pip install tox
-  tox
-
-The testrunner accepts a ``--coverage`` argument to enable code
-coverage metrics through the `coverage.py`_ package. That would go
-something like this::
-
-  cd src/greentest
-  python testrunner.py --coverage
-  coverage combine
-  coverage html -i
-  <open htmlcov/index.html>
+.. image:: https://travis-ci.org/gevent/gevent.svg?branch=master
+   :target: https://travis-ci.org/gevent/gevent
 
-Builds on Travis CI automatically submit updates to `coveralls.io`_ to
-monitor test coverage.
+.. image:: https://ci.appveyor.com/api/projects/status/q4kl21ng2yo2ixur?svg=true
+   :target: https://ci.appveyor.com/project/denik/gevent
 
 .. image:: https://coveralls.io/repos/gevent/gevent/badge.svg?branch=master&service=github
    :target: https://coveralls.io/github/gevent/gevent?branch=master
 
-.. note:: On Debian, you will probably need ``libpythonX.Y-testsuite``
-          installed to run all the tests.
+.. include:: doc/_about.rst
 
-Continuous integration
-----------------------
+Read the documentation online at http://www.gevent.org.
 
-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
-Windows.
+Post feedback and issues on the `bug tracker`_, `mailing list`_, blog_
+and `twitter (@gevent)`_.
 
-.. image:: https://travis-ci.org/gevent/gevent.svg?branch=master
-   :target: https://travis-ci.org/gevent/gevent
 
-.. image:: https://ci.appveyor.com/api/projects/status/q4kl21ng2yo2ixur?svg=true
-   :target: https://ci.appveyor.com/project/denik/gevent
+.. include:: doc/install.rst
 
-.. _gevent: http://www.gevent.org
-.. _greenlet: http://pypi.python.org/pypi/greenlet
-.. _libev: http://libev.schmorp.de/
-.. _libuv: http://libuv.org/
-.. _c-ares: http://c-ares.haxx.se/
-.. _inspired by eventlet: http://blog.gevent.org/2010/02/27/why-gevent/
-.. _use gevent: http://groups.google.com/group/gevent/browse_thread/thread/4de9703e5dca8271
-.. _open source projects based on gevent: https://github.com/gevent/gevent/wiki/Projects
-.. _Python Package Index: http://pypi.python.org/pypi/gevent
-.. _the repository: https://github.com/gevent/gevent
 .. _bug tracker: https://github.com/gevent/gevent/wiki/Projects
 .. _mailing list: http://groups.google.com/group/gevent
 .. _blog: http://blog.gevent.org
 .. _twitter (@gevent): http://twitter.com/gevent
-.. _coverage.py: https://pypi.python.org/pypi/coverage/
-.. _coveralls.io: https://coveralls.io/github/gevent/gevent
-.. _AppVeyor: https://ci.appveyor.com/project/denik/gevent
-.. _what's new: http://www.gevent.org/whatsnew_1_3.html
-.. _changelog: http://www.gevent.org/changelog.html

_setuputils.py

@@ -42,10 +42,10 @@
 def quoted_abspath(*segments):
     return '"' + os.path.abspath(os.path.join(*segments)) + '"'
 
-def read(name, *args):
+def read(*names):
     """Read a file path relative to this file."""
-    with open(os.path.join(THIS_DIR, name)) as f:
-        return f.read(*args)
+    with open(os.path.join(THIS_DIR, *names)) as f:
+        return f.read()
 
 def read_version(name="src/gevent/__init__.py"):
     contents = read(name)

doc/_about.rst

@@ -1,25 +1,55 @@
+..
+  This file is included in README.rst from the top-level
+  so it is limited to pure ReST markup, not Sphinx.
+
+
+
 gevent is a coroutine_ -based Python_ networking library that uses
-greenlet_ to provide a high-level synchronous API on top of the `libev`_
+`greenlet <https://greenlet.readthedocs.io>`_ to provide a high-level synchronous API on top of the `libev`_
 or `libuv`_ event loop.
 
 Features include:
 
 
-* Fast event loop based on `libev`_ or `libuv`_
-* Lightweight execution units based on greenlet_.
+* Fast event loop based on `libev`_ or `libuv`_.
+* Lightweight execution units based on greenlets.
 * API that re-uses concepts from the Python standard library (for
-  examples there are :class:`events <gevent.event.Event>` and
-  :class:`queues <gevent.queue.Queue>`).
-* :ref:`Cooperative sockets with SSL support <networking>`
-* :doc:`Cooperative DNS queries <dns>` performed through a threadpool,
+  examples there are `events`_ and
+  `queues`_).
+* `Cooperative sockets with SSL support <http://www.gevent.org/api/index.html#networking>`_
+* `Cooperative DNS queries <http://www.gevent.org/dns.html>`_ performed through a threadpool,
   dnspython, or c-ares.
-* :ref:`Monkey patching utility <monkey-patching>` to get 3rd party modules to become cooperative
+* `Monkey patching utility <http://www.gevent.org/intro.html#monkey-patching>`_ to get 3rd party modules to become cooperative
 * TCP/UDP/HTTP servers
-* Subprocess support (through :mod:`gevent.subprocess`)
+* Subprocess support (through `gevent.subprocess`_)
 * Thread pools
 
+gevent is `inspired by eventlet`_ but features a more consistent API,
+simpler implementation and better performance. Read why others `use
+gevent`_ and check out the list of the `open source projects based on
+gevent`_.
+
+gevent was written by `Denis Bilenko <http://denisbilenko.com/>`_.
+
+Since version 1.1, gevent is maintained by Jason Madden for
+`NextThought <https://nextthought.com>`_ with help from the
+`contributors <https://github.com/gevent/gevent/graphs/contributors>`_
+and is licensed under the MIT license.
+
+See `what's new`_ in the latest major release.
+
+Check out the detailed changelog_ for this version.
+
+.. _events: http://www.gevent.org/api/gevent.event.html#gevent.event.Event
+.. _queues: http://www.gevent.org/api/gevent.queue.html#gevent.queue.Queue
+.. _gevent.subprocess: http://www.gevent.org/api/gevent.subprocess.html#module-gevent.subprocess
+
 .. _coroutine: https://en.wikipedia.org/wiki/Coroutine
 .. _Python: http://python.org
-.. _greenlet: https://greenlet.readthedocs.io
 .. _libev: http://software.schmorp.de/pkg/libev.html
 .. _libuv: http://libuv.org
+.. _inspired by eventlet: http://blog.gevent.org/2010/02/27/why-gevent/
+.. _use gevent: http://groups.google.com/group/gevent/browse_thread/thread/4de9703e5dca8271
+.. _open source projects based on gevent: https://github.com/gevent/gevent/wiki/Projects
+.. _what's new: http://www.gevent.org/whatsnew_1_3.html
+.. _changelog: http://www.gevent.org/changelog.html

doc/contents.rst

@@ -8,6 +8,7 @@ Introduction and Basics
 .. toctree::
    :maxdepth: 2
 
+   install
    intro
    whatsnew_1_3
    api/gevent

doc/index.rst

@@ -5,20 +5,6 @@
 .. include:: _about.rst
 
 
-gevent is `inspired by eventlet
-<http://blog.gevent.org/2010/02/27/why-gevent/>`_ but features more
-consistent API, simpler implementation and better performance. Read
-why others `use gevent
-<http://groups.google.com/group/gevent/browse_thread/thread/4de9703e5dca8271>`_
-and check out the list of the `open source projects based on gevent. <https://github.com/gevent/gevent/wiki/Projects>`_
-
-gevent was written by `Denis Bilenko <http://denisbilenko.com/>`_.
-
-Since version 1.1, gevent is maintained by Jason Madden for
-`NextThought <https://nextthought.com>`_ with help from the
-`contributors <https://github.com/gevent/gevent/graphs/contributors>`_.
-
-gevent is licensed under the MIT license.
 
 :ref:`Continue reading <installation>` »