Reorganize docs.

Move the API reference to its own (sectioned) page to clean up the main page. Break up the massive 'gevent' module page into more digestable parts and add more xrefs.

.gitignore

@@ -34,16 +34,6 @@ src/greentest/.coverage
 
 doc/_build
 doc/__pycache__
-doc/gevent.*.rst
-!doc/gevent.core.rst
-!doc/gevent.event.rst
-!doc/gevent.hub.rst
-!doc/gevent.queue.rst
-!doc/gevent.pool.rst
-!doc/gevent.threadpool.rst
-!doc/gevent.socket.rst
-!doc/gevent.ssl.rst
-!doc/gevent.wsgi.rst
 
 # Artifacts of configuring in place
 deps/c-ares/config.log

doc/api/gevent._socket2.rst

+==================================================
+ :mod:`gevent._socket2` -- Python 2 socket module
+==================================================
+
+.. automodule:: gevent._socket2
+    :members:

doc/api/gevent._socket3.rst

+==================================================
+ :mod:`gevent._socket3` -- Python 3 socket module
+==================================================
+
+.. automodule:: gevent._socket3
+    :members:

doc/api/gevent._ssl2.rst

+=================================================================================
+ :mod:`gevent._ssl2` -- SSL wrapper for socket objects on Python 2.7.8 and below
+=================================================================================
+
+.. automodule:: gevent._ssl2
+    :members:

doc/api/gevent._ssl3.rst

+===================================================================
+ :mod:`gevent._ssl3` -- SSL wrapper for socket objects on Python 3
+===================================================================
+
+.. automodule:: gevent._ssl3
+    :members:

doc/api/gevent._sslgte279.rst

+======================================================================================
+ :mod:`gevent._sslgte279` -- SSL wrapper for socket objects on Python 2.7.9 and above
+======================================================================================
+
+.. automodule:: gevent._sslgte279
+    :members:

doc/api/gevent.ares.rst

+======================================================================================
+ :mod:`gevent.ares` -- Backwards compatibility alias for :mod:`gevent.resolver.cares`
+======================================================================================
+
+.. automodule:: gevent.ares
+    :members:

doc/api/gevent.backdoor.rst

+======================================================================================================
+ :mod:`gevent.backdoor` -- Interactive greenlet-based network console that can be used in any process
+======================================================================================================
+
+.. automodule:: gevent.backdoor
+    :members:

doc/api/gevent.baseserver.rst

+=================================================================
+ :mod:`gevent.baseserver` -- Base class for implementing servers
+=================================================================
+
+.. automodule:: gevent.baseserver
+    :members:

doc/api/gevent.builtins.rst

+================================================================================
+ :mod:`gevent.builtins` -- gevent friendly implementations of builtin functions
+================================================================================
+
+.. automodule:: gevent.builtins
+    :members:

doc/api/gevent.events.rst

+:mod:`gevent.events` -- Publish/subscribe event infrastructure
+==============================================================
+
+.. automodule:: gevent.events
+    :members:

doc/api/gevent.exceptions.rst

+========================================
+ :mod:`gevent.exceptions` -- Exceptions
+========================================
+
+.. automodule:: gevent.exceptions
+    :members:

doc/api/gevent.fileobject.rst

+============================================================================
+ :mod:`gevent.fileobject` -- Wrappers to make file-like objects cooperative
+============================================================================
+
+.. automodule:: gevent.fileobject
+    :members:

doc/gevent.rst → doc/api/gevent.greenlet.rst

-====================================================
- :mod:`gevent` -- basic utilities and configuration
-====================================================
+==================
+ Greenlet Objects
+==================
 
-.. module:: gevent
+.. currentmodule:: gevent
 
-The most common functions and classes are available in the :mod:`gevent` top level package.
+:class:`gevent.Greenlet` is a light-weight cooperatively-scheduled
+execution unit. It is a more powerful version of
+:class:`greenlet.greenlet`. For general information, see :ref:`greenlet-basics`.
 
-.. autodata:: __version__
+You can retrieve the current greenlet at any time using
+:func:`gevent.getcurrent`.
 
-Greenlet objects
-================
-
-:class:`Greenlet` is a light-weight cooperatively-scheduled execution unit.
+Starting Greenlets
+==================
 
 To start a new greenlet, pass the target function and its arguments to
 :class:`Greenlet` constructor and call :meth:`Greenlet.start`:
@@ -24,42 +25,53 @@ does the same:
 
 >>> g = Greenlet.spawn(myfunction, 'arg1', 'arg2', kwarg1=1)
 
+There are also various spawn helpers in :mod:`gevent`, including:
+
+- :func:`gevent.spawn`
+- :func:`gevent.spawn_later`
+- :func:`gevent.spawn_raw`
+
+Stopping Greenlets
+==================
+
+You can forcibly stop a :class:`Greenlet` using its :meth:`Greenlet.kill`
+method. There are also helper functions that can be useful in limited
+circumstances (if you might have a :class:`raw greenlet <greenlet.greenlet>`):
+
+- :func:`gevent.kill`
+- :func:`gevent.killall`
+
+.. _subclassing-greenlet:
+
+Subclassing Greenlet
+====================
+
 To subclass a :class:`Greenlet`, override its ``_run()`` method and
-call ``Greenlet.__init__(self)`` in the subclass ``__init__``.  It also a good
-idea to override :meth:`Greenlet.__str__`: if ``_run`` raises an exception,
-its string representation will be printed after the traceback it
-generated.
+call ``Greenlet.__init__(self)`` in the subclass ``__init__``. This
+can be done to override :meth:`Greenlet.__str__`: if ``_run`` raises
+an exception, its string representation will be printed after the
+traceback it generated.
 
-    .. important:: You *SHOULD NOT* attempt to override the ``run()`` method.
+::
 
-.. class:: Greenlet
+    class MyNoopGreenlet(Greenlet):
 
-.. automethod:: Greenlet.__init__
+        def __init__(self, seconds):
+            Greenlet.__init__(self)
+            self.seconds = seconds
 
-.. autoattribute:: Greenlet.exception
-.. autoattribute:: Greenlet.minimal_ident
-.. autoattribute:: Greenlet.name
-.. autoattribute:: Greenlet.dead
+        def _run(self):
+            gevent.sleep(self.seconds)
 
-.. rubric:: Methods
+        def __str__(self):
+            return 'MyNoopGreenlet(%s)' % self.seconds
+
+
+.. important:: You *SHOULD NOT* attempt to override the ``run()`` method.
 
-.. automethod:: Greenlet.spawn
-.. automethod:: Greenlet.ready
-.. automethod:: Greenlet.successful
-.. automethod:: Greenlet.start
-.. automethod:: Greenlet.start_later
-.. automethod:: Greenlet.join
-.. automethod:: Greenlet.get
-.. automethod:: Greenlet.kill(exception=GreenletExit, block=True, timeout=None)
-.. automethod:: Greenlet.link(callback)
-.. automethod:: Greenlet.link_value(callback)
-.. automethod:: Greenlet.link_exception(callback)
-.. automethod:: Greenlet.rawlink
-.. automethod:: Greenlet.unlink
-.. automethod:: Greenlet.__str__
 
 Boolean Contexts
-----------------
+================
 
 Greenlet objects have a boolean value (``__nonzero__`` or
 ``__bool__``) which is true if it's active: started but not dead yet.
@@ -77,24 +89,6 @@ switched to yet or is already dead. While the latter is OK, the former
 is not good, because a just spawned Greenlet has not been switched to
 yet and thus would evaluate to False.
 
-Raw greenlet Methods
---------------------
-
-Being a greenlet__ subclass, :class:`Greenlet` also has `switch()
-<switching>`_ and `throw() <throw>`_ methods. However, these should
-not be used at the application level as they can very easily lead to
-greenlets that are forever unscheduled. Prefer higher-level safe
-classes, like :class:`Event <gevent.event.Event>` and :class:`Queue
-<gevent.queue.Queue>`, instead.
-
-__ https://greenlet.readthedocs.io/en/latest/#instantiation
-.. _switching: https://greenlet.readthedocs.io/en/latest/#switching
-.. _throw: https://greenlet.readthedocs.io/en/latest/#methods-and-attributes-of-greenlets
-
-.. class:: greenlet.greenlet
-
-    The base class from which `Greenlet` descends.
-
 .. exception:: GreenletExit
 
     A special exception that kills the greenlet silently.
@@ -104,103 +98,52 @@ __ https://greenlet.readthedocs.io/en/latest/#instantiation
     The exception instance is available under :attr:`value <Greenlet.value>`
     property as if it was returned by the greenlet, not raised.
 
-Spawn helpers
-=============
-
-.. autofunction:: spawn
-.. autofunction:: spawn_later
-.. autofunction:: spawn_raw
-
-
-Useful general functions
-========================
-
-.. seealso:: :mod:`gevent.util`
 
-.. function:: getcurrent()
-
-   Return the currently executing greenlet (the one that called this
-   function). Note that this may be an instance of :class:`Greenlet`
-   or :class:`greenlet.greenlet`.
-
-Sleeping
---------
-
-.. autofunction:: sleep
-
-.. autofunction:: idle
-
-Stopping Greenlets
-------------------
-
-.. autofunction:: kill(greenlet, exception=GreenletExit)
-
-.. autofunction:: killall(greenlets, exception=GreenletExit, block=True, timeout=None)
-
-Waiting
--------
-
-.. autofunction:: wait
-
-.. autofunction:: iwait
-
-.. autofunction:: joinall
-
-Working with muliple processes
-------------------------------
-
-.. autofunction:: fork
-
-.. autofunction:: reinit
-
-Signals
--------
-
-.. function:: signal(signalnum, handler, *args, **kwargs)
-
-    Call the *handler* with the *args* and *kwargs* when the process
-    receives the signal *signalnum*.
-
-    The *handler* will be run in a new greenlet when the signal is delivered.
-
-    This returns an object with the useful method ``cancel``, which, when called,
-    will prevent future deliveries of *signalnum* from calling *handler*.
-
-    .. note::
-
-        This may not operate correctly with SIGCHLD if libev child watchers
-        are used (as they are by default with :func:`gevent.os.fork`).
+.. class:: Greenlet
 
-    .. versionchanged:: 1.1b4
+.. automethod:: Greenlet.__init__
 
-         This is an alias for ``gevent.hub.signal``, included for
-         backwards compatibility; the new module :doc:`gevent.signal <gevent.signal>`
-         is replacing this name. This alias will be removed in a
-         future release.
+.. autoattribute:: Greenlet.exception
+.. autoattribute:: Greenlet.minimal_ident
+.. autoattribute:: Greenlet.name
+.. autoattribute:: Greenlet.dead
 
-    .. versionchanged:: 1.2a1
+.. rubric:: Methods
 
-          The *handler* is required to be callable at construction time.
+.. automethod:: Greenlet.spawn
+.. automethod:: Greenlet.ready
+.. automethod:: Greenlet.successful
+.. automethod:: Greenlet.start
+.. automethod:: Greenlet.start_later
+.. automethod:: Greenlet.join
+.. automethod:: Greenlet.get
+.. automethod:: Greenlet.kill(exception=GreenletExit, block=True, timeout=None)
+.. automethod:: Greenlet.link(callback)
+.. automethod:: Greenlet.link_value(callback)
+.. automethod:: Greenlet.link_exception(callback)
+.. automethod:: Greenlet.rawlink
+.. automethod:: Greenlet.unlink
+.. automethod:: Greenlet.__str__
 
-.. This is also in the docstring of gevent.hub.signal, which is the
-   actual callable invoked
 
-Timeouts
-========
+Raw greenlet Methods
+====================
 
-.. autoclass:: Timeout
-    :members:
-    :undoc-members:
-    :special-members: __enter__, __exit__
+Being a greenlet__ subclass, :class:`Greenlet` also has `switch()
+<switching>`_ and `throw() <throw>`_ methods. However, these should
+not be used at the application level as they can very easily lead to
+greenlets that are forever unscheduled. Prefer higher-level safe
+classes, like :class:`Event <gevent.event.Event>` and :class:`Queue
+<gevent.queue.Queue>`, instead.
 
-.. autofunction:: with_timeout
+__ https://greenlet.readthedocs.io/en/latest/#instantiation
+.. _switching: https://greenlet.readthedocs.io/en/latest/#switching
+.. _throw: https://greenlet.readthedocs.io/en/latest/#methods-and-attributes-of-greenlets
 
-.. _gevent-configuration:
+.. class:: greenlet.greenlet
 
-Configuration
-=============
+    The base class from which `Greenlet` descends.
 
-.. autoclass:: gevent._config.Config
 
 ..  LocalWords:  Greenlet GreenletExit Greenlet's greenlet's
 ..  LocalWords:  automethod

doc/api/gevent.local.rst

+===============================================
+ :mod:`gevent.local` -- Greenlet-local objects
+===============================================
+
+.. automodule:: gevent.local
+    :members:

doc/api/gevent.lock.rst

+==========================================
+ :mod:`gevent.lock` -- Locking primitives
+==========================================
+
+.. automodule:: gevent.lock
+    :members:

doc/api/gevent.monkey.rst

+===============================================================
+ :mod:`gevent.monkey` -- Make the standard library cooperative
+===============================================================
+
+.. automodule:: gevent.monkey
+    :members:

doc/api/gevent.os.rst

+=========================================================================
+ :mod:`gevent.os` -- Low-level operating system functions from :mod:`os`
+=========================================================================
+
+.. automodule:: gevent.os
+    :members:

doc/api/gevent.pywsgi.rst

+====================================================================
+ :mod:`gevent.pywsgi` -- A pure-Python, gevent-friendly WSGI server
+====================================================================
+
+.. automodule:: gevent.pywsgi
+    :members:

doc/api/gevent.rst

+===================================
+ :mod:`gevent` -- common functions
+===================================
+
+.. module:: gevent
+
+The most common functions and classes are available in the
+:mod:`gevent` top level package.
+
+Please read :doc:`/intro` for an introduction to the concepts
+discussed here.
+
+.. autodata:: __version__
+
+See :class:`gevent.Greenlet` for information about greenlet objects.
+
+.. seealso:: :mod:`gevent.util`
+
+Creating Greenlets
+==================
+
+.. autofunction:: spawn
+.. autofunction:: spawn_later
+.. autofunction:: spawn_raw
+
+
+Getting Greenlets
+=================
+
+.. function:: getcurrent()
+
+   Return the currently executing greenlet (the one that called this
+   function). Note that this may be an instance of :class:`Greenlet`
+   or :class:`greenlet.greenlet`.
+
+Stopping Greenlets
+==================
+
+.. autofunction:: kill(greenlet, exception=GreenletExit)
+
+.. autofunction:: killall(greenlets, exception=GreenletExit, block=True, timeout=None)
+
+
+Sleeping
+========
+
+.. autofunction:: sleep
+
+.. autofunction:: idle
+
+
+Waiting
+=======
+
+.. autofunction:: wait
+
+.. autofunction:: iwait
+
+.. autofunction:: joinall
+
+Working with muliple processes
+==============================
+
+.. note::
+   These functions will only be available if :func:`os.fork` is
+   available. In general, prefer to use :func:`gevent.os.fork` instead
+   of manually calling these functions.
+
+.. autofunction:: fork
+
+.. autofunction:: reinit
+
+Signals
+=======
+
+.. function:: signal_handler(signalnum, handler, *args, **kwargs)
+
+    Call the *handler* with the *args* and *kwargs* when the process
+    receives the signal *signalnum*.
+
+    The *handler* will be run in a new greenlet when the signal is delivered.
+
+    This returns an object with the useful method ``cancel``, which, when called,
+    will prevent future deliveries of *signalnum* from calling *handler*.
+
+    .. note::
+
+        This may not operate correctly with SIGCHLD if libev child watchers
+        are used (as they are by default with :func:`gevent.os.fork`).
+
+    .. versionchanged:: 1.1b4
+
+         ``gevent.signal`` is an alias for this function, included for
+         backwards compatibility; the new module :doc:`gevent.signal <gevent.signal>`
+         is replacing this name. This alias will be removed in a
+         future release.
+
+    .. versionchanged:: 1.2a1
+
+          The *handler* is required to be callable at construction time.
+
+.. This is also in the docstring of gevent.hub.signal, which is the
+   actual callable invoked
+
+Timeouts
+========
+
+See class :class:`gevent.Timeout` for information about Timeout objects.
+
+.. autofunction:: with_timeout
+
+..  LocalWords:  Greenlet GreenletExit Greenlet's greenlet's
+..  LocalWords:  automethod

doc/synchronization.rst → doc/api/gevent.select.rst

 ====================================================
- Synchronization primitives (locks, queues, events)
+ :mod:`gevent.select` -- Waiting for I/O completion
 ====================================================
 
-.. toctree::
-
-   gevent.event
-   gevent.queue
-   gevent.lock
+.. automodule:: gevent.select
+    :members:

doc/api/gevent.server.rst

+========================================
+ :mod:`gevent.server` -- TCP/SSL server
+========================================
+
+.. automodule:: gevent.server
+    :members:

doc/api/gevent.signal.rst

+==============================================================================================
+ :mod:`gevent.signal` -- Cooperative implementation of special cases of :func:`signal.signal`
+==============================================================================================
+
+.. automodule:: gevent.signal
+    :members:

doc/api/gevent.subprocess.rst

+===============================================================
+ :mod:`gevent.subprocess` -- Cooperative ``subprocess`` module
+===============================================================
+
+.. automodule:: gevent.subprocess
+    :members:

doc/api/gevent.thread.rst

+===================================================================================================
+ :mod:`gevent.thread` -- Implementation of the standard :mod:`thread` module that spawns greenlets
+===================================================================================================
+
+.. automodule:: gevent.thread
+    :members:

doc/api/gevent.threading.rst

+============================================================================================
+ :mod:`gevent.threading` -- Implementation of the standard :mod:`threading` using greenlets
+============================================================================================
+
+.. automodule:: gevent.threading
+    :members:

doc/api/gevent.time.rst

+:mod:`gevent.time` -- Makes *sleep* gevent aware
+================================================
+
+This module has all the members of :mod:`time`, but the *sleep*
+function is :func:`gevent.sleep`.
+
+.. automodule:: gevent.time
+    :members:

doc/api/gevent.timeout.rst

+======================
+ Cooperative Timeouts
+======================
+
+Cooperative timeouts can be implemented with the
+:class:`gevent.Timeout` class, and the helper function
+:func:`gevent.with_timeout`.
+
+.. autoclass:: gevent.Timeout
+    :members:
+    :undoc-members:
+    :special-members: __enter__, __exit__

doc/api/gevent.util.rst

+===========================================
+ :mod:`gevent.util` -- Low-level utilities
+===========================================
+
+.. automodule:: gevent.util
+    :members:

doc/api/index.rst

+===============
+ API reference
+===============
+
+High-level concepts
+===================
+.. toctree::
+
+   gevent
+   gevent.timeout
+   gevent.greenlet
+
+.. _networking:
+
+Networking interfaces
+=====================
+
+.. toctree::
+
+   gevent.socket
+   gevent.ssl
+   gevent.select
+
+Synchronization primitives (locks, queues, events)
+==================================================
+
+.. toctree::
+
+   gevent.event
+   gevent.queue
+   gevent.lock
+
+Low-level details
+=================
+
+.. toctree::
+
+   gevent.hub
+   gevent.core
+
+Module Listing
+==============
+
+.. This should be sorted alphabetically
+
+.. toctree::
+
+   gevent.backdoor
+   gevent.baseserver
+   gevent.builtins
+   gevent.core
+   gevent.event
+   gevent.events
+   gevent.exceptions
+   gevent.fileobject
+   gevent.hub
+   gevent.local
+   gevent.lock
+   gevent.monkey
+   gevent.os
+   gevent.pool
+   gevent.pywsgi
+   gevent.queue
+   gevent.queue
+   gevent.resolver.ares
+   gevent.resolver.blocking
+   gevent.resolver.dnspython
+   gevent.resolver.thread
+   gevent.select
+   gevent.server
+   gevent.server
+   gevent.signal
+   gevent.socket
+   gevent.ssl
+   gevent.subprocess
+   gevent.thread
+   gevent.threading
+   gevent.threadpool
+   gevent.time
+   gevent.util
+
+
+Deprecated Modules
+==================
+
+.. toctree::
+
+   gevent.ares
+   gevent.wsgi
+
+Examples
+========
+
+.. toctree::
+
+   /examples/index

doc/community.rst

-Community
-=========
+===========
+ Community
+===========
 
 The official mailing list is hosted on `Google Groups (gevent)`_. To
 subscribe via email, send a message to
@@ -26,7 +27,7 @@ You're also welcome to join `#gevent`_ IRC channel on freenode.
 
 
 Russian group
--------------
+=============
 
 Русскоязычная группа находится здесь: `Google Groups (gevent-ru)`_. Чтобы подписаться, отправьте сообщение на gevent-ru+subscribe@googlegroups.com
 

doc/conf.py

@@ -19,8 +19,6 @@ import os
 # for better documentation extraction and ease of tweaking docs.
 os.environ['PURE_PYTHON'] = '1'
 
-os.system('%s generate_rst.py generate' % sys.executable)
-
 sys.path.append('.')  # for mysphinxext
 
 # If extensions (or modules to document with autodoc) are in another directory,

doc/configuration.rst

+.. _gevent-configuration:
+
+====================
+ Configuring gevent
+====================
+
+
+.. autoclass:: gevent._config.Config

doc/contents.rst

-Table Of Contents
-=================
+===================
+ Table Of Contents
+===================
+
+Introduction and Basics
+=======================
 
 .. toctree::
    :maxdepth: 2
 
    intro
    whatsnew_1_3
+   configuration
+   api/gevent
+   servers
+   dns
    changelog
-   reference
-   examples/index
+
+API Details
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   api/index
+
+Related Information
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   success
+   community
    older_releases
 
+
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`

doc/dns.rst

@@ -40,7 +40,7 @@ relative performance and correctness tradeoffs.
 
 .. toctree::
 
-   gevent.resolver.thread
-   gevent.resolver.ares
-   gevent.resolver.dnspython
-   gevent.resolver.blocking
+   api/gevent.resolver.thread
+   api/gevent.resolver.ares
+   api/gevent.resolver.dnspython
+   api/gevent.resolver.blocking

doc/examples/concurrent_download.rst

-=============================
-Example concurrent_download.py
-=============================
+================================
+ Example concurrent_download.py
+================================
 .. literalinclude:: ../../examples/concurrent_download.py
   :language: python
   :linenos:
 
 `Current source <https://github.com/gevent/gevent/blob/master/examples/concurrent_download.py>`_
-

doc/generate_rst.py

-#!/usr/bin/env python
-from __future__ import print_function
-import os
-import glob
-from os.path import join, dirname, abspath, basename
-
-
-# do not generate .rst for the following modules as they imported into gevent package
-# and covered there
-SKIP = ['hub', 'timeout', 'greenlet']
-
-
-template = '''.. AUTOGENERATED -- will be overwritten (remove this comment to save changes)
-
-%(title)s
-%(title_underline)s
-
-.. automodule:: gevent.%(module)s
-    :members:
-    :undoc-members:
-'''
-
-def _find_modules():
-    try:
-        import gevent
-    except ImportError:
-        print("Failed to import gevent, no modules found")
-        return ()
-
-    directory = dirname(abspath(gevent.__file__))
-    print('Imported gevent from %s' % (directory, ))
-    modules = glob.glob(join(directory, '*.py')) + glob.glob(join(directory, '*.pyc'))
-    modules = set(basename(filename).split('.')[0] for filename in modules)
-    modules = set(name for name in modules
-                  if name.startswith('_socket2') or name.startswith('_socket3') or name.startswith('_ssl')
-                  or not name.startswith('_'))
-    return modules
-
-import warnings
-warnings.simplefilter('ignore', DeprecationWarning)
-
-modules = _find_modules()
-
-def _read(fname, count):
-    with open(fname) as f:
-        return f.read(count)
-
-
-def generate_rst_for_module(module, do=True):
-    rst_filename = 'gevent.%s.rst' % module
-    exists = os.path.exists(rst_filename)
-    if exists:
-        autogenerated = 'autogenerated' in _read(rst_filename, 200).lower()
-        if not autogenerated:
-            return
-    m = __import__('gevent.%s' % module)
-    m = getattr(m, module)
-    title = getattr(m, '__doc__', None)
-    if title:
-        lines = title.strip().splitlines()
-        for line in lines:
-            # skip leading blanks. Support both styles of docstrings.
-            if line:
-                title = line.strip()
-                break
-        title = title.strip(' .')
-    prefix = ':mod:`gevent.%s`' % module
-    if title:
-        title = prefix + ' -- %s' % (title, )
-    else:
-        title = prefix
-    title_underline = '=' * len(title)
-    params = globals().copy()
-    params.update(locals())
-    result = template % params
-    if getattr(m, '_no_undoc_members', True):
-        result = '\n'.join(result.splitlines()[:-1])
-    if exists:
-        if _read(rst_filename, len(result) + 1) == result:
-            return  # already exists one which is the same
-    if do:
-        print('Generated %s from %s' % (rst_filename, m.__file__))
-        with open(rst_filename, 'w') as f:
-            f.write(result)
-    else:
-        print('Would generate %s from %s' % (rst_filename, m.__file__))
-
-
-def generate_rst(do=True):
-    assert os.path.exists('contents.rst'), 'Wrong directory, contents.rst not found'
-    for module in modules:
-        if module not in SKIP:
-            try:
-                generate_rst_for_module(module, do=do)
-            except ImportError as e:
-                print("Failed to import and generate module", module, e)
-
-def iter_autogenerated():
-    for module in modules:
-        rst_filename = 'gevent.%s.rst' % module
-        exists = os.path.exists(rst_filename)
-        if exists:
-            autogenerated = 'autogenerated' in open(rst_filename).read(200).lower()
-            if autogenerated:
-                yield rst_filename
-
-
-if __name__ == '__main__':
-    import sys
-    if sys.argv[1:] == ['show']:
-        for filename in iter_autogenerated():
-            print(filename)
-    elif sys.argv[1:] == ['delete']:
-        for filename in iter_autogenerated():
-            print('Removing', filename)
-            os.unlink(filename)
-    elif sys.argv[1:] == ['generate']:
-        generate_rst()
-    elif sys.argv[1:] == []:
-        generate_rst(do=False)
-    else:
-        sys.exit('Invalid command line: %s' % (sys.argv[1:], ))

doc/index.rst

@@ -10,8 +10,10 @@ Features include:
 
 * **Fast event loop** based on libev or libuv (epoll on Linux, kqueue on FreeBSD).
 * **Lightweight execution units** based on greenlet.
-* API that re-uses concepts from the Python standard library (for example there are :class:`gevent.event.Events` and :class:`gevent.queue.Queues`).
-* :doc:`Cooperative sockets with SSL support <networking>`
+* 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>`
 * DNS queries performed through threadpool or c-ares.
 * :ref:`Monkey patching utility <monkey-patching>` to get 3rd party modules to become cooperative
 

doc/intro.rst

@@ -243,6 +243,7 @@ useful in the cooperative world:
   allows passing a value or an exception to the waiters.
 - :class:`~queue.Queue` and :class:`~queue.JoinableQueue`.
 
+.. _greenlet-basics:
 
 Lightweight pseudothreads
 =========================
@@ -277,30 +278,17 @@ The traceback is asynchronously printed to ``sys.stderr`` when the greenlet dies
 - :meth:`kill <gevent.Greenlet.kill>` -- interrupts greenlet's execution;
 - :meth:`get <gevent.Greenlet.get>`  -- returns the value returned by greenlet or re-raises the exception that killed it.
 
-It is possible to customize the string printed after the traceback by
-subclassing the :class:`~gevent.Greenlet` class and redefining its
-``__str__`` method.
+Greenlets can be subclassed with care. One use for this is to
+customize the string printed after the traceback by subclassing the
+:class:`~gevent.Greenlet` class and redefining its ``__str__`` method.
+For more information, see :ref:`subclassing-greenlet`.
 
-To subclass a :class:`gevent.Greenlet`, override its ``_run`` method
-and call ``Greenlet.__init__(self)`` in ``__init__``::
-
-    class MyNoopGreenlet(Greenlet):
-
-        def __init__(self, seconds):
-            Greenlet.__init__(self)
-            self.seconds = seconds
-
-        def _run(self):
-            gevent.sleep(self.seconds)
-
-        def __str__(self):
-            return 'MyNoopGreenlet(%s)' % self.seconds
 
 Greenlets can be killed synchronously from another greenlet. Killing
 will resume the sleeping greenlet, but instead of continuing
 execution, a :exc:`GreenletExit` will be raised.
 
-    >>> g = MyNoopGreenlet(4)
+    >>> g = Greenlet(gevent.sleep, 4)
     >>> g.start()
     >>> g.kill()
     >>> g.dead
@@ -315,12 +303,12 @@ raised.
 
 The :meth:`kill <gevent.Greenlet.kill>` method can accept a custom exception to be raised:
 
-    >>> g = MyNoopGreenlet.spawn(5) # spawn() creates a Greenlet and starts it
+    >>> g = Greenlet.spawn(gevent.sleep, 5) # spawn() creates a Greenlet and starts it
     >>> g.kill(Exception("A time to kill"))
     Traceback (most recent call last):
      ...
     Exception: A time to kill
-    MyNoopGreenlet(5) failed with Exception
+    Greenlet(5) failed with Exception
 
 The :meth:`kill <gevent.Greenlet.kill>` can also accept a *timeout*
 argument specifying the number of seconds to wait for the greenlet to
@@ -374,17 +362,28 @@ The :class:`socket <gevent.socket.socket>` and :class:`SSLObject
 <gevent.ssl.SSLObject>` instances can also have a timeout, set by the
 :meth:`settimeout <socket.socket.settimeout>` method.
 
-When these are not enough, the :class:`~gevent.Timeout` class can be used to
-add timeouts to arbitrary sections of (cooperative, yielding) code.
+When these are not enough, the :class:`gevent.Timeout` class and
+:func:`gevent.with_timeout` can be used to add timeouts to arbitrary
+sections of (cooperative, yielding) code.
 
 
-Further reading
+Further Reading
 ===============
 
-To limit concurrency, use the :class:`gevent.pool.Pool` class (see :doc:`examples/dns_mass_resolve`).
+To limit concurrency, use the :class:`gevent.pool.Pool` class (see
+:doc:`examples/dns_mass_resolve`).
 
 Gevent comes with TCP/SSL/HTTP/WSGI servers. See :doc:`servers`.
 
+There are a number of configuration options for gevent. See
+:ref:`gevent-configuration` for details. This document also explains how
+to enable gevent's builtin monitoring and debugging features.
+
+The objects in :mod:`gevent.util` may be helpful for monitoring and
+debugging purposes.
+
+See :doc:`api/index` for a complete API reference.
+
 
 External resources
 ==================

doc/lowlevel.rst

-===================
- Low-level details
-===================
-
-.. toctree::
-
-   gevent.hub
-   gevent.core

doc/networking.rst

-======================================
- Networking interfaces (sockets, SSL)
-======================================
-
-.. toctree::
-
-   gevent.socket
-   gevent.ssl
-   gevent.select

doc/reference.rst

-API reference
--------------
-
-.. toctree::
-
-   gevent
-   networking
-   synchronization
-   servers
-   dns
-   gevent.backdoor
-   gevent.fileobject
-   gevent.local
-   gevent.monkey
-   gevent.os
-   gevent.signal
-   gevent.pool
-   gevent.queue
-   gevent.server
-   gevent.subprocess
-   gevent.thread
-   gevent.threading
-   gevent.threadpool
-   gevent.time
-   gevent.util
-   gevent.events
-   lowlevel

doc/servers.rst

-.. implementing-servers:
+.. _implementing-servers:
 
 ======================
  Implementing servers
@@ -43,6 +43,17 @@ The :mod:`gevent.pywsgi` module contains an implementation of a :pep:`3333`
 :class:`WSGI server <gevent.pywsgi.WSGIServer>`. In addition,
 gunicorn_ is a stand-alone server that supports gevent.
 
+API Reference
+=============
+
+- :doc:`api/gevent.baseserver`
+- :doc:`api/gevent.server`
+- :doc:`api/gevent.pywsgi`
+
+
+Examples
+========
+
 More :doc:`examples <examples/index>` are available:
 
 - :doc:`examples/echoserver` - demonstrates :class:`gevent.server.StreamServer`
@@ -50,11 +61,5 @@ More :doc:`examples <examples/index>` are available:
 - :doc:`examples/wsgiserver_ssl` - demonstrates :class:`WSGIServer with ssl <gevent.pywsgi.WSGIServer>`
 
 
-.. _gunicorn: http://gunicorn.org
-
-.. toctree::
 
-   gevent.baseserver
-   gevent.server
-   gevent.pywsgi
-   gevent.wsgi
+.. _gunicorn: http://gunicorn.org

doc/success.rst

-Success stories
-===============
+=================
+ Success stories
+=================
 
-If you have a success story for Gevent, contact denis.bilenko@gmail.com or post to the `google group`_.
+If you have a success story for gevent, contact post to the `google group`_.
 
 .. _google group: http://groups.google.com/group/gevent/
 
 
 Omegle_
--------
+=======
 
 I've been using gevent to power Omegle, my high-volume chat site,
 since 2010. Omegle is used by nearly half a million people every day,
@@ -32,7 +33,7 @@ library.
 
 
 Pediapress_
------------
+===========
 
 Pediapress_ powers Wikipedia_'s PDF rendering cluster. I've started using
 gevent in 2009 after our NFS based job queue showed serious performance
@@ -51,7 +52,7 @@ much cleaner and much more manageable then before.
 
 
 `ESN Social Software`_
-----------------------
+======================
 
 Wanting to avoid the ravages of asynchronous programming we choose to base
 our real-time web development framework Planet on gevent and Python. We’ve
@@ -64,7 +65,7 @@ enough for our needs and our customer’s requirements.
 
 
 `Blue Shell Games`_
--------------------
+===================
 
 At Blue Shell Games we use gevent to power the application servers that
 connect more than a million daily players of our social casino games.
@@ -83,7 +84,7 @@ of problems with ease.
 
 
 TellApart_
-----------
+==========
 
 At TellApart, we have been using gevent since 2010 as the underpinnings of
 our frontend servers. It enables us to serve millions of requests every hour
@@ -103,7 +104,7 @@ See also: `Gevent at TellApart`_
 
 
 Disqus
-------
+======
 
 See: `Making Disqus Realtime`_
 
@@ -111,7 +112,7 @@ See: `Making Disqus Realtime`_
 
 
 Pinterest
----------
+=========
 
 Pinterest is one of the biggest players of gevents. We started using gevent in
 2011 to query our mysql shards concurrently. It served us well so far. We run

src/gevent/__init__.py

@@ -46,7 +46,8 @@ __all__ = [
     'sleep',
     'idle',
     'kill',
-    'signal',
+    'signal', # deprecated
+    'signal_handler',
     'fork',
     'reinit',
     'getswitchinterval',
@@ -106,6 +107,7 @@ except ImportError:
 # to treat 'from gevent import signal' as a callable, to matter whether
 # the 'gevent.signal' module has been imported first
 from gevent.hub import signal as _signal_class
+signal_handler = _signal_class
 from gevent import signal as _signal_module
 
 # The object 'gevent.signal' must:

src/gevent/_socketcommon.py

@@ -161,7 +161,7 @@ def gethostbyname(hostname):
 
     Return the IP address (a string of the form '255.255.255.255') for a host.
 
-    .. seealso:: :doc:`dns`
+    .. seealso:: :doc:`/dns`
     """
     return get_hub().resolver.gethostbyname(hostname)
 
@@ -174,7 +174,7 @@ def gethostbyname_ex(hostname):
     for a host.  The host argument is a string giving a host name or IP number.
     Resolve host and port into list of address info entries.
 
-    .. seealso:: :doc:`dns`
+    .. seealso:: :doc:`/dns`
     """
     return get_hub().resolver.gethostbyname_ex(hostname)
 
@@ -194,7 +194,7 @@ def getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0):
     narrow the list of addresses returned. Passing zero as a value for each of
     these arguments selects the full range of results.
 
-    .. seealso:: :doc:`dns`
+    .. seealso:: :doc:`/dns`
     """
     return get_hub().resolver.getaddrinfo(host, port, family, socktype, proto, flags)
 
@@ -220,7 +220,7 @@ def gethostbyaddr(ip_address):
     Return the true host name, a list of aliases, and a list of IP addresses,
     for a host.  The host argument is a string giving a host name or IP number.
 
-    .. seealso:: :doc:`dns`
+    .. seealso:: :doc:`/dns`
     """
     return get_hub().resolver.gethostbyaddr(ip_address)
 
@@ -231,7 +231,7 @@ def getnameinfo(sockaddr, flags):
 
     Get host and port for a sockaddr.
 
-    .. seealso:: :doc:`dns`
+    .. seealso:: :doc:`/dns`
     """
     return get_hub().resolver.getnameinfo(sockaddr, flags)
 

src/gevent/monkey.py

@@ -658,7 +658,7 @@ def patch_socket(dns=True, aggressive=True):
     sockets.
 
     :keyword bool dns: When true (the default), also patch address
-        resolution functions in :mod:`socket`. See :doc:`dns` for details.
+        resolution functions in :mod:`socket`. See :doc:`/dns` for details.
     """
     from gevent import socket
     # Note: although it seems like it's not strictly necessary to monkey patch 'create_connection',
@@ -678,7 +678,7 @@ def patch_socket(dns=True, aggressive=True):
 @_ignores_DoNotPatch
 def patch_dns():
     """
-    Replace :doc:`DNS functions <dns>` in :mod:`socket` with
+    Replace :doc:`DNS functions </dns>` in :mod:`socket` with
     cooperative versions.
 
     This is only useful if :func:`patch_socket` has been called and is