Socket and SSL docs. [skip ci]

.gitignore

@@ -16,6 +16,8 @@ doc/gevent.*.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

doc/generate_rst.py

@@ -26,7 +26,8 @@ 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 not name.startswith('_'))
+              if name.startswith('_socket2') or name.startswith('_socket3') or name.startswith('_ssl')
+              or not name.startswith('_'))
 
 import warnings
 warnings.simplefilter('ignore', DeprecationWarning)

doc/gevent.socket.rst

+====================================================================
+ :mod:`gevent.socket` -- Cooperative low-level networking interface
+====================================================================
+
+This module provides socket operations and some related functions. The
+API of the functions and classes matches the API of the corresponding
+items in the standard :mod:`socket` module exactly, but the
+synchronous functions in this module only block the current greenlet
+and let the others run.
+
+For convenience, exceptions (like :class:`error <socket.error>` and
+:class:`timeout <socket.timeout>`) as well as the constants from the
+:mod:`socket` module are imported into this module.
+
+
+The exact API exposed by this module varies depending on what version
+of Python you are using. The documents below describe the API for
+Python 2 and Python 3, respectively.
+
+.. warning:: All the described APIs should be imported from
+   ``gevent.socket``, and *not* from their implementation modules.
+   Their organization is an implementation detail that may change at
+   any time.
+
+.. toctree::
+
+   Python 3 interface <gevent._socket3>
+   Python 2 interface <gevent._socket2>
+
+
+Shared Functions
+================
+
+These functions are identical and shared by all implementations.
+
+.. autofunction:: gevent.socket.create_connection

doc/gevent.ssl.rst

+====================================================================
+ :mod:`gevent.ssl` -- Secure Sockets Layer (SSL/TLS) module
+====================================================================
+
+This module provides SSL/TLS operations and some related functions. The
+API of the functions and classes matches the API of the corresponding
+items in the standard :mod:`ssl` module exactly, but the
+synchronous functions in this module only block the current greenlet
+and let the others run.
+
+The exact API exposed by this module varies depending on what version
+of Python you are using. The documents below describe the API for
+Python 3, Python 2.7.9 and above, and Python 2.7.8 and below, respectively.
+
+.. warning:: All the described APIs should be imported from
+   ``gevent.ssl``, and *not* from their implementation modules.
+   Their organization is an implementation detail that may change at
+   any time.
+
+.. toctree::
+
+   Python 3 interface <gevent._ssl3>
+   Python 2.7.9 and above interface (including PyPy 2.6.0) <gevent._sslgte279>
+   Python 2.7.8 and below interface (including PyPy 2.5.0) <gevent._ssl2>

doc/index.rst

@@ -33,8 +33,8 @@ If you like gevent, :doc:`donate <sfc>` to support the development.
 What are others saying?
 =======================
 
-Twitter
--------
+Twitter @gevent
+---------------
 
 .. raw:: html
 

gevent/_ssl2.py

 # Wrapper module for _ssl. Written by Bill Janssen.
 # Ported to gevent by Denis Bilenko.
-"""SSL wrapper for socket objects.
+"""SSL wrapper for socket objects on Python 2.7.8 and below.
 
 For the documentation, refer to :mod:`ssl` module manual.
 
@@ -21,6 +21,12 @@ from gevent.socket import socket, _fileobject, timeout_default
 from gevent.socket import error as socket_error, EWOULDBLOCK
 from gevent.hub import string_types, PYPY
 
+try:
+    long
+except NameError:
+    # Make us importable under Py3k for documentation
+    long = int
+
 
 __implements__ = ['SSLSocket',
                   'wrap_socket',

gevent/_ssl3.py

 # Wrapper module for _ssl. Written by Bill Janssen.
 # Ported to gevent by Denis Bilenko.
-"""SSL wrapper for socket objects.
+"""SSL wrapper for socket objects on Python 3.
 
 For the documentation, refer to :mod:`ssl` module manual.
 

gevent/_sslgte279.py

 # Wrapper module for _ssl. Written by Bill Janssen.
 # Ported to gevent by Denis Bilenko.
-"""SSL wrapper for socket objects.
+"""SSL wrapper for socket objects on Python 2.7.9 and above.
 
 For the documentation, refer to :mod:`ssl` module manual.