Minor doc reorganization.

Surface the older changelogs more directly, and also surfate the module listing more directly.

Fixes #1700.

CHANGES.rst

@@ -380,6 +380,3 @@ Misc
 ----
 
 - See :issue:`1367`.
-
-
-----

docs/api/gevent.hub.rst

-============================
- The Event Loop and the Hub
-============================
+=============================================
+ ``gevent.hub`` - The Event Loop and the Hub
+=============================================
 
 .. module:: gevent.hub
 

docs/api/gevent.rst

@@ -10,9 +10,16 @@ The most common functions and classes are available in the
 Please read :doc:`/intro` for an introduction to the concepts
 discussed here.
 
+.. seealso:: :mod:`gevent.util`
+
+.. seealso:: :doc:`/configuration`
+
+             For configuring gevent using the environment or the
+             ``gevent.config`` object.
+
+
 .. autodata:: __version__
 
-.. seealso:: :mod:`gevent.util`
 
 Working With Greenlets
 ======================

docs/api/gevent.timeout.rst

-======================
- Cooperative Timeouts
-======================
+===============================================
+ Cooperative Timeouts Using ``gevent.Timeout``
+===============================================
 
 Cooperative timeouts can be implemented with the
 :class:`gevent.Timeout` class, and the helper function

docs/api/index.rst

@@ -2,8 +2,14 @@
  API reference
 ===============
 
+Functional Areas
+================
+
+This section of the document groups gevent APIs by functional area.
+For an alphabetical listing by module, see :ref:`api_module_listing`.
+
 High-level concepts
-===================
+-------------------
 .. toctree::
 
    gevent
@@ -13,7 +19,7 @@ High-level concepts
 .. _networking:
 
 Networking interfaces
-=====================
+---------------------
 
 .. toctree::
 
@@ -23,7 +29,7 @@ Networking interfaces
    gevent.selectors
 
 Synchronization primitives (locks, queues, events)
-==================================================
+--------------------------------------------------
 
 .. toctree::
 
@@ -33,20 +39,25 @@ Synchronization primitives (locks, queues, events)
    gevent.lock
 
 Low-level details
-=================
+-----------------
 
 .. toctree::
 
    gevent.hub
    gevent.core
 
+.. _api_module_listing:
+
 Module Listing
 ==============
 
+This section of the document groups gevent APIs by module.
+
 .. This should be sorted alphabetically
 
 .. toctree::
 
+   gevent
    gevent.backdoor
    gevent.baseserver
    gevent.builtins
@@ -82,7 +93,9 @@ Module Listing
 
 
 Deprecated Modules
-==================
+------------------
+
+These modules are deprecated and should not be used in new code.
 
 .. toctree::
 

docs/changelog.rst

 .. include:: ../CHANGES.rst
+
+
+Older Releases
+==============
+
+For full information on older versions, see :doc:`older_releases`.
+
+.. toctree::
+   :caption: Older change logs, without context.
+   :maxdepth: 2
+
+   changelog_1_5
+   changelog_1_4
+   changelog_1_3
+   changelog_1_2
+   changelog_1_1
+   changelog_1_0
+   changelog_pre

docs/contents.rst

@@ -2,6 +2,8 @@
  Table Of Contents
 ===================
 
+.. tip:: To jump directly to the full API reference, see :doc:`api/index`.
+
 Introduction and Basics
 =======================
 
@@ -9,8 +11,8 @@ Introduction and Basics
    :maxdepth: 2
 
    install
+   changelog
    intro
-   whatsnew_1_5
    api/gevent
    api/gevent.greenlet
    servers
@@ -18,13 +20,13 @@ Introduction and Basics
    monitoring
    loop_impls
    configuration
-   changelog
 
-API Details
-===========
+
+Coding With gevent
+==================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    api/index
 

docs/older_releases.rst

@@ -3,11 +3,24 @@
 ==================================
 
 .. toctree::
+   :caption: Release announcements
    :maxdepth: 2
 
+   whatsnew_1_5
    whatsnew_1_4
    whatsnew_1_3
    whatsnew_1_2
    whatsnew_1_1
    whatsnew_1_0
+
+.. toctree::
+   :caption: Older change logs, without context.
+   :maxdepth: 2
+
+   changelog_1_5
+   changelog_1_4
+   changelog_1_3
+   changelog_1_2
+   changelog_1_1
+   changelog_1_0
    changelog_pre

docs/whatsnew_1_3.rst

@@ -10,7 +10,7 @@
    changelog_1_3
 
 Detailed information on what has changed is available in the
-:doc:`changelog`. This document summarizes the most important changes
+:doc:`changelog_1_3`. This document summarizes the most important changes
 since :doc:`gevent 1.2 <whatsnew_1_2>`.
 
 gevent 1.3 is an important update for performance, debugging and

docs/whatsnew_1_4.rst

@@ -10,7 +10,7 @@
    changelog_1_4
 
 Detailed information on what has changed is available in the
-:doc:`changelog`. This document summarizes the most important changes
+:doc:`changelog_1_4`. This document summarizes the most important changes
 since :doc:`gevent 1.3 <whatsnew_1_3>`.
 
 gevent 1.4 is a small maintenance release featuring bug fixes and a

docs/whatsnew_1_5.rst

@@ -10,7 +10,7 @@
    changelog_1_5
 
 Detailed information on what has changed is available in the
-:doc:`changelog`. This document summarizes the most important changes
+:doc:`changelog_1_5`. This document summarizes the most important changes
 since :doc:`gevent 1.4 <whatsnew_1_4>`.
 
 gevent 1.5 is a maintenance and feature release including bug fixes and a