cleanup doc; replace all the boilerplace .rst files with a script that generates them

doc/_templates/contentstable.html

-<table class="contentstable" width=50%><tr>
-<td width="50%">
-<p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{{ _('Contents') }}</a><br>
-<span class="linkdescr">{{ _('lists all sections and subsections') }}</span></p>
-<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{{ _('Search Page') }}</a><br>
-<span class="linkdescr">{{ _('search this documentation') }}</span></p>
-</td><td width="50%">
-<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{{ _('Index') }}</a><br>
-<span class="linkdescr">{{ _('all functions, classes, terms') }}</span></p>
-<p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">{{ _('Module Index') }}</a><br>
-<span class="linkdescr">{{ _('quick access to all modules') }}</span></p>
-</td></tr>
-</table>

doc/conf.py

@@ -13,6 +13,8 @@
 
 import sys, os
 
+os.system('%s generate_rst.py generate' % sys.executable)
+
 sys.path.append('.') # for mysphinxext
 
 if not os.path.exists('changelog.rst') and os.path.exists('../changelog.rst'):
@@ -135,7 +137,7 @@ html_short_title = 'Documentation'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -150,7 +152,7 @@ html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-html_additional_pages = {'contentstable': 'contentstable.html'}
+#html_additional_pages = {'contentstable': 'contentstable.html'}
 
 # If false, no module index is generated.
 html_use_modindex = True
@@ -162,7 +164,7 @@ html_use_index = True
 #html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the

doc/contents.rst

-gevent documentation contents
-=============================
+Table Of Contents
+=================
 
 .. toctree::
 

doc/generate_rst.py

+#!/usr/bin/env python
+import os
+import glob
+from os.path import join, dirname, abspath, basename
+import gevent
+
+
+# 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:
+'''
+
+directory = dirname(abspath(gevent.__file__))
+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 not name.startswith('_'))
+
+
+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 open(rst_filename).read(200).lower()
+        if not autogenerated:
+            return
+    m = __import__('gevent.%s' % module)
+    m = getattr(m, module)
+    title = getattr(m, '__doc__', None)
+    if title:
+        title = title.strip().split('\n')[0]
+        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 exists:
+        if open(rst_filename).read(len(result) + 1) == result:
+            return # already exists one which is the same
+    if do:
+        print 'Generated %s' % rst_filename
+        open(rst_filename, 'w').write(result)
+    else:
+        print 'Would generate %s' % rst_filename
+
+
+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:
+            generate_rst_for_module(module, do=do)
+
+
+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():
+            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/gevent.core.rst

-Low-level wrappers around libevent (gevent.core module)
+:mod:`gevent.core` - Low-level wrappers around libevent
 =======================================================
 
 .. automodule:: gevent.core

doc/gevent.dns.rst

-Synchronous wrappers around libevent-dns
-========================================
-
-.. automodule:: gevent.dns
-    :members:
-    :undoc-members:
-

doc/gevent.event.rst

-Synchronization primitives (gevent.event module)
-================================================
+:mod:`gevent.event` -- Notifications of multiple listeners
+==========================================================
 
 .. module:: gevent.event
 

doc/gevent.http.rst

-HTTP server based on libevent-http (gevent.http module)
-=======================================================
-
-.. automodule:: gevent.http
-	:members:
-	:undoc-members:

doc/gevent.monkey.rst

-Monkey patching (gevent.monkey module)
-======================================
-
-.. automodule:: gevent.monkey
-    :members:
-    :undoc-members:
-

doc/gevent.pool.rst

-Managing greenlets in a group
-=============================
-
-.. automodule:: gevent.pool
-    :members:
-    :undoc-members:
-

doc/gevent.queue.rst

-Synchronized queues (gevent.queue module)
-=========================================
+:mod:`gevent.queue` -- Synchronized queues
+==========================================
 
 .. automodule:: gevent.queue
 	:members:

doc/gevent.rawgreenlet.rst

-:mod:`gevent.rawgreenlet`
-=========================
-
-.. automodule:: gevent.rawgreenlet
-	:members:
-	:undoc-members:

doc/gevent.rst

-Basic utilities (The gevent top level package)
-==============================================
+:mod:`gevent` -- basic utilities
+================================
 
 .. module:: gevent
 
@@ -20,18 +20,8 @@ or use classmethod :meth:`spawn` which is a shortcut that does the same:
 
 >>> g = Greenlet.spawn(myfunction, 'arg1', 'arg2', kwarg1=1)
 
-To subclass a :class:`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)
-
-It also a good idea to override __str__(): if _run() raises an exception, its string representation will be printed after the traceback it generated.
+To subclass a :class:`Greenlet`, override its _run() method and call ``Greenlet.__init__(self)`` in :meth:`__init__`:
+It also a good idea to override :meth:`__str__`: if :meth:`_run` raises an exception, its string representation will be printed after the traceback it generated.
 
 .. class:: Greenlet
 

doc/gevent.socket.rst

-Cooperative socket module (gevent.socket module)
-================================================
-
-.. automodule:: gevent.socket
-    :members:
-    :undoc-members:
-

doc/gevent.ssl.rst

-gevent.ssl - SSL wrapper for socket objects
-===========================================
-
-.. automodule:: gevent.ssl
-    :members: none
-
-

doc/gevent.util.rst

-Random utilities
-================
-
-gevent.select module
---------------------
-
-.. automodule:: gevent.select
-   :members:
-
-
-Python helpers (gevent.util module)
------------------------------------
-
-.. automodule:: gevent.util
-   :members:
-   :undoc-members:
-

doc/gevent.wsgi.rst

-WSGI server based on libevent-http (gevent.wsgi module)
-=======================================================
-
-.. automodule:: gevent.wsgi
-	:members:
-	:undoc-members:

doc/networking.rst

+Networking interfaces
+---------------------
+
+.. toctree::
+
+   gevent.socket
+   gevent.ssl
+   gevent.sslold
+   gevent.dns
+   gevent.select
+

doc/reference.rst

@@ -4,14 +4,13 @@ API reference
 .. toctree::
 
    gevent
-   gevent.event
-   gevent.queue
-   gevent.socket
-   gevent.monkey
-   gevent.http
-   gevent.wsgi
+   networking
+   synchronization
    gevent.pool
-   gevent.util
-   gevent.dns
+   servers
+   gevent.local
+   gevent.monkey
    gevent.core
+   gevent.backdoor
+   helpers
 

doc/servers.rst

+
+.. implementing-servers:
+
+Implementing servers
+--------------------
+
+There are a few classes to simplify server implementation with gevent. They all share the similar interface::
+
+  def handle(socket, address):
+       print 'new connection!'
+
+  server = StreamServer(('127.0.0.1', 1234), handle) # creates a new server
+  server.start() # start accepting new connections
+
+At this point, any new connection accepted on ``127.0.0.1:1234`` will result in a new
+:class:`Greenlet` spawned using *handle* function. To stop a server use :meth:`stop` method.
+
+In case of a :class:`WSGIServer`, handle must be a WSGI application callable.
+
+It is possible to limit the maximum number of concurrent connections, by passing a :class:`Pool` instance::
+
+  pool = Pool(10000) # do not accept more than 10000 connections
+  server = StreamServer(('127.0.0.1', 1234), handle, spawn=pool)
+  server.serve_forever()
+
+The :meth:`server_forever` method calls :meth:`start` and then waits until interrupted or until the server is stopped.
+
+The difference between :class:`wsgi.WSGIServer <gevent.wsgi.WSGIServer>` and :class:`pywsgi.WSGIServer <gevent.pywsgi.WSGIServer>`
+is that the first one is very fast as it uses libevent's http server implementation but it shares the issues that
+libevent-http has. In particular:
+
+- `does not support streaming`_: the responses are fully buffered in memory before sending; likewise, the incoming requests are loaded in memory in full;
+- `pipelining does not work`_: the server uses ``"Connection: close"`` by default;
+- does not support SSL.
+
+The :class:`pywsgi.WSGIServer <gevent.pywsgi.WSGIServer>` does not have these limitations.
+In addition, gunicorn_ is a stand-alone server that supports gevent. Gunicorn has its own HTTP parser but can also use :mod:`gevent.wsgi` module.
+
+More examples are available in the `code repository`_:
+
+- `echoserver.py`_ - demonstrates :class:`StreamServer`
+- `wsgiserver.py`_ - demonstrates :class:`wsgi.WSGIServer <gevent.wsgi.WSGIServer>`
+- `wsgiserver_ssl.py`_ - demonstrates :class:`pywsgi.WSGIServer <gevent.pywsgi.WSGIServer>`
+
+.. _`code repository`: http://bitbucket.org/denis/gevent/src/tip/examples/#source-path
+.. _`does not support streaming`: http://code.google.com/p/gevent/issues/detail?id=4
+.. _`pipelining does not work`: http://code.google.com/p/gevent/issues/detail?id=32
+.. _gunicorn: http://gunicorn.org
+.. _`echoserver.py`: http://bitbucket.org/denis/gevent/src/tip/examples/echoserver.py#cl-9
+.. _`wsgiserver.py`: http://bitbucket.org/denis/gevent/src/tip/examples/wsgiserver.py#cl-4
+.. _`wsgiserver_ssl.py`: http://bitbucket.org/denis/gevent/src/tip/examples/wsgiserver_ssl.py#cl-4
+.. _`httpserver.py`: http://bitbucket.org/denis/gevent/src/tip/examples/httpserver.py#cl-4
+
+.. toctree::
+
+   gevent.server
+   gevent.pywsgi
+   gevent.wsgi
+
+

doc/synchronization.rst

+Synchronization primitives
+--------------------------
+
+.. toctree::
+
+   gevent.event
+   gevent.queue
+   gevent.coros
+