Add a 1.1 what's new page. Some doc love for the intro. [skip ci]

doc/conf.py

@@ -48,6 +48,9 @@ extlinks = {'issue': ('https://github.com/gevent/gevent/issues/%s',
             'pr': ('https://github.com/gevent/gevent/pull/%s',
                    'pull request #')}
 
+autodoc_default_flags = ['members', 'show-inheritance']
+autoclass_content = 'both'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -99,14 +102,14 @@ add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'perldoc'
 
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['gevent.']
@@ -252,4 +255,4 @@ class MyClassDocumenter(ClassDocumenter):
         members.sort(key=key)
         return members_check_module, members
 
-autodoc.ClassDocumenter = MyClassDocumenter
+#autodoc.ClassDocumenter = MyClassDocumenter

doc/contents.rst

@@ -4,8 +4,9 @@ Table Of Contents
 .. toctree::
 
    intro
-   whatsnew_1_0
+   whatsnew_1_1
    reference
+   whatsnew_1_0
    changelog
 
 * :ref:`genindex`

doc/whatsnew_1_0.rst

-What's new gevent 1.0
----------------------
+==========================
+ What's new in gevent 1.0
+==========================
 
 The detailed information is available in changelog. Below is the summary of all changes since 0.13.8.
 
 Gevent 1.0 supports Python 2.5 - 2.7. The version of greenlet required is 0.3.2. The source distribution
-now includes the dependencies (libev and c-ares) and has not dependencies other than greenlet.
+now includes the dependencies (libev and c-ares) and has no dependencies other than greenlet.
 
 
 New core
-~~~~~~~~
+========
 
-New event loop is used libev instead of libevent (see http://blog.gevent.org/2011/04/28/libev-and-libevent/ for motivation).
+Now the event loop is using libev instead of libevent (see http://blog.gevent.org/2011/04/28/libev-and-libevent/ for motivation).
 
 The new :mod:`gevent.core` has been rewritten to wrap libev's API. (On Windows, the :mod:`gevent.core` accepts Windows handles
 rather than stdio file descriptors.).
@@ -26,7 +27,7 @@ Thus ``sys.exit()`` when run inside a greenlet is no longer trapped and kills th
 
 
 New dns resolver
-~~~~~~~~~~~~~~~~
+================
 
 Two new DNS resolvers: threadpool-based one (enabled by default) and c-ares based one. That threadpool-based resolver was added mostly for Windows and Mac OS X platforms where c-ares might behave differently w.r.t system configuration. On Linux, however, the c-ares based resolver is probably a better choice. To enable c-ares resolver set GEVENT_RESOLVER=ares environment variable.
 
@@ -46,7 +47,7 @@ It is possible to implement your own DNS resolver and make gevent use it. The GE
 
 
 New API
-~~~~~~~
+=======
 
 - :func:`gevent.wait` and :func:`gevent.iwait`
 - UDP server: gevent.server.DatagramServer
@@ -66,10 +67,10 @@ New API
 
 
 Breaking changes
-~~~~~~~~~~~~~~~~
+================
 
 Removed features
-^^^^^^^^^^^^^^^^
+----------------
 
 - gevent.dns module (wrapper around libevent-dns)
 - gevent.http module (wrapper around libevent-http)
@@ -84,20 +85,20 @@ Renamed gevent.coros to gevent.lock. The gevent.coros is still available but dep
 
 
 API changes
-^^^^^^^^^^^
+-----------
 
 In all servers, method "kill" was renamed to "close". The old name is available as deprecated alias.
 
 - ``Queue(0)`` is now equivalent to an unbound queue and raises :exc:`DeprecationError`. Use :class:`gevent.queue.Channel` if you need a channel.
 
-The :class:`Greenlet` objects:
+The :class:`gevent.Greenlet` objects:
 
 - Added ``__nonzero__`` implementation that returns `True` after greenlet was started until it's dead. This overrides
   greenlet's __nonzero__ which returned `False` after `start()` until it was first switched to.
 
 
 Bugfixes
-~~~~~~~~
+========
 
 - Issue #302: "python -m gevent.monkey" now sets __file__ properly.
 - Issue #143: greenlet links are now executed in the order they were added

doc/whatsnew_1_1.rst

+==========================
+ What's new in gevent 1.1
+==========================
+
+Detailed information an what has changed is avaialble in the
+:doc:`changelog`. This document summarizes the most important changes
+since gevent 1.0.3.
+
+Platform Support
+================
+
+gevent 1.1 support Python 2.6, 2.7, 3.3, and 3.4 on the CPython (python.org)
+interpreter. It also supports PyPy 2.5.0 and above (with best results
+being obtained on PyPy 2.7.0 and above); PyPy3 is not supported.
+
+Support for Python 2.5 was removed when support for Python 3 was
+added. Any further releases in the 1.0.x line will maintain support
+for Python 2.5.
+
+Improved subprocess support
+===========================
+
+In gevent 1.0, support and monkey patching for the ``subprocess``
+module was added. Monkey patching was off by default.
+
+In 1.1, monkey patching subprocess is on by default due to
+improvements in handling child processes and requirements by
+downstream libraries, notably `gunicorn`_.
+
+- :func:`gevent.os.fork`, which is monkey patched by default (and
+  should be used to fork a gevent-aware process that expects to use
+  gevent in the child process) has been improved and cooperates with
+  :func:`gevent.os.waitpid` (again monkey patched by default).
+- fork-watchers will be called, even in multi-threaded programs.
+- The default threadpool and threaded resolver work in child
+  processes.
+- File descriptors are no longer leaked if
+  :class:`gevent.subprocess.Popen` fails to start the child.
+
+In addition, simple use of :class:`multiprocessing.Process` is now
+possible in a monkey patched system, at least on POSIX platforms.
+
+.. note:: All of the above entail forking a child process. Forking
+		  a child process that uses gevent, greenlets, and libev
+		  can have some unexpected consequences if the child
+		  doesn't immediately ``exec`` a new binary. Be sure you
+		  understand these consequences before using this
+		  functionality, especially late in a program's lifecycle.
+		  For a more robust solution to certain uses of child
+		  process, consider `gipc`_.
+
+.. _gunicorn: http://gunicorn.org
+.. _gipc: https://gehrcke.de/gipc/
+
+Monkey patching
+===============
+
+Monkey patching is more robust, especially if the standard library
+:mod:`threading` or :mod:`logging` modules had been imported before
+applying the patch. In addition, there are now supported ways to
+determine if something has been monkey patched.
+
+API Additions
+=============
+
+Numerous APIs offer slightly expanded functionality in this version. Highlights
+include:
+
+- A gevent-friendly version of :obj:`select.poll` (on platforms that
+  implement it).
+- :class:`gevent.fileobject.FileObjectPosix` uses the :mod:`io`
+  package on both Python 2 and Python 3, increasing its functionality
+  correctness, and performance. (Previously, the Python 2 implementation used the
+  undocumented :class:`socket._fileobject`.)
+- Locks raise the same error as standard library locks if they are
+  over-released.
+- :meth:`ThreadPool.apply <gevent.threadpool.ThreadPool.apply>` can
+  now be used recursively.
+- The various pool objects (:class:`gevent.pool.Group`,
+  :class:`gevent.pool.Pool`, :class:`gevent.threadpool.ThreadPool`)
+  support the same improved APIs: ``imap`` and ``imap_unordered``
+  accept multiple iterables, ``apply`` raises any exception raised by
+  the target callable.
+- Killing a greenlet (with :func:`gevent.kill` or
+  :meth:`Greenlet.kill <gevent.Greenlet.kill>`) before it is actually started and
+  switched to now prevents the greenlet from ever running, instead of
+  raising an exception when it is later switched to.
+- Almost anywhere that gevent raises an exception from one greenlet to
+  another (e.g., :meth:`Greenlet.get <gevent.Greenlet.get>`),
+  the original traceback is preserved and raised.
+
+
+Compatibility
+=============
+
+This release is intended to be compatible with 1.0.x with minimal or
+no changes to client source code. However, there are a few changes to
+be aware of that might affect some applications. Most of these changes
+are due to the increased platform support of Python 3 and PyPy and
+reduce the cases of undocumented or non-standard behaviour.
+
+- :class:`gevent.baseserver.BaseServer` deterministically
+  `closes its sockets <https://github.com/gevent/gevent/issues/248#issuecomment-82467350>`_.
+
+  As soon as a request completes (the request handler returns),
+  the ``BaseServer`` and its subclasses including
+  :class:`gevent.server.StreamServer` and
+  :class:`gevent.pywsgi.WSGIServer` close the client socket.
+
+  In gevent 1.0, the client socket was left to the mercies of the
+  garbage collector. In the typical case, the socket would still
+  be closed as soon as the request handler returned due to
+  CPython's reference-counting garbage collector. But this meant
+  that a reference cycle could leave a socket dangling open for
+  an indeterminate amount of time, and a reference leak would
+  result in it never being closed. It also meant that Python 3
+  would produce ResourceWarnings, and PyPy (which, unlike
+  CPython, does not use a reference-counted GC) would only close
+  (and flush) the socket at an arbitrary time in the future.
+
+  If your application relied on the socket not being closed when
+  the request handler returned (e.g., you spawned a greenlet that
+  continued to use the socket) you will need to keep the request
+  handler from returning (e.g., ``join`` the greenlet) or
+  subclass the server to prevent it from closing the socket; the
+  former approach is strongly preferred.
+
+- :class:`gevent.pywsgi.WSGIServer` ensures that headers set by the
+  application can be encoded in the ISO-8859-1 charset.
+
+  Under gevent 1.0, non-``bytes`` headers (that is, ``unicode`` since
+  gevent 1.0 only ran on Python 2) were encoded according to the
+  current default Python encoding. In some cases, this could allow
+  non-Latin-1 characters to be sent in the headers, but this violated
+  the HTTP specification, and their interpretation by the recipient is
+  unknown. Now, a UnicodeError will be raised.
+
+  Most applications that adhered to the WSGI PEP, `PEP 3333`_ will not
+  need to make any changes. See :issue:`614` for more discussion.
+
+  .. _`PEP 3333`: https://www.python.org/dev/peps/pep-3333/
+
+- Under Python 2, the previously undocumented ``timeout`` parameter to
+  :meth:`Popen.wait <gevent.subprocess.Popen.wait>` (a gevent extension
+  ) now throws an exception, just like the documented parameter to the
+  same stdlib method in Python 3.