More restructuring of the docs.

README.rst

@@ -1,27 +1,33 @@
+.. This file is included into docs/history.rst
+
 .. image:: https://secure.travis-ci.org/python-greenlet/greenlet.png
    :target: http://travis-ci.org/python-greenlet/greenlet
 
-The greenlet package is a spin-off of Stackless, a version of CPython
-that supports micro-threads called "tasklets". Tasklets run
+Greenlets are lightweight coroutines for in-process concurrent
+programming.
+
+The "greenlet" package is a spin-off of `Stackless`_, a version of
+CPython that supports micro-threads called "tasklets". Tasklets run
 pseudo-concurrently (typically in a single or a few OS-level threads)
 and are synchronized with data exchanges on "channels".
 
 A "greenlet", on the other hand, is a still more primitive notion of
-micro-thread with no implicit scheduling; coroutines, in other
-words. This is useful when you want to control exactly when your code
-runs. You can build custom scheduled micro-threads on top of greenlet;
+micro-thread with no implicit scheduling; coroutines, in other words.
+This is useful when you want to control exactly when your code runs.
+You can build custom scheduled micro-threads on top of greenlet;
 however, it seems that greenlets are useful on their own as a way to
 make advanced control flow structures. For example, we can recreate
 generators; the difference with Python's own generators is that our
 generators can call nested functions and the nested functions can
-yield values too. Additionally, you don't need a "yield" keyword. See
-the example in tests/test_generator.py.
+yield values too. (Additionally, you don't need a "yield" keyword. See
+the example in `test_generator.py
+<https://github.com/python-greenlet/greenlet/blob/adca19bf1f287b3395896a8f41f3f4fd1797fdc7/src/greenlet/tests/test_generator.py#L1>`_).
 
-Greenlets are provided as a C extension module for the regular
-unmodified interpreter.
+Greenlets are provided as a C extension module for the regular unmodified
+interpreter.
+
+.. _`Stackless`: http://www.stackless.com
 
-Greenlets are lightweight coroutines for in-process concurrent
-programming.
 
 Who is using Greenlet?
 ======================
@@ -45,7 +51,7 @@ The easiest way to get Greenlet is to install it with pip::
   pip install greenlet
 
 
-Source code archives and windows installers are available on the
+Source code archives and binary distributions are vailable on the
 python package index at https://pypi.org/project/greenlet
 
 The source code repository is hosted on github:

docs/api.rst

@@ -24,7 +24,7 @@ Greenlets
 
       Switches execution to this greenlet. See :ref:`switching`.
 
-   .. automethod:: throw([typ, [val, [tb]]])
+   .. automethod:: throw
 
    .. autoattribute:: dead
 

docs/creating_executing_greenlets.rst

@@ -1,6 +1,9 @@
-==========================================================
- Creating And Executing Greenlets: The Greenlet Lifecycle
-==========================================================
+==================================
+ Creating And Executing Greenlets
+==================================
+
+.. This document is a mess. It's a cross between how-to and API
+   reference.
 
 .. currentmodule:: greenlet
 
@@ -50,6 +53,11 @@ The ``run`` attribute is deleted at that time.
    ...
    AttributeError: run
 
+.. _subclassing_greenlet:
+
+Subclassing greenlet
+====================
+
 You can also subclass :class:`greenlet.greenlet` and define ``run`` as
 a method. This is useful to store additional state with the greenlet.
 
@@ -71,13 +79,16 @@ a method. This is useful to store additional state with the greenlet.
 
 See :ref:`switching` for more information about switching into greenlets.
 
+.. _changing_the_parent:
+
 Changing The Parent
 ===================
 
-When a greenlet finishes, execution resumes with its parent. This
-defaults to the current greenlet when the object was instantiated, but
-can be changed either at that time or any time later. To set it at
-creation time, pass the desired parent as the second argument:
+When a greenlet finishes, :ref:`execution resumes with its parent
+<greenlet_parents>`. This defaults to the current greenlet when the
+object was instantiated, but can be changed either at that time or any
+time later. To set it at creation time, pass the desired parent as the
+second argument:
 
 .. doctest::
 
@@ -91,7 +102,7 @@ creation time, pass the desired parent as the second argument:
    In the child.
    In the parent.
 
-To change it later, assign to the :attr:`greenlet.parent` attribute.
+To change it later, assign to the ``greenlet.parent`` attribute.
 
 .. doctest::