Explicitly publish and link to examples so they're consistent with a given release.

[skip ci]

doc/contents.rst

@@ -8,6 +8,7 @@ Table Of Contents
    whatsnew_1_3
    changelog
    reference
+   examples/index
    older_releases
 
 * :ref:`genindex`

doc/examples/concurrent_download.rst

+=============================
+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/examples/dns_mass_resolve.rst

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

doc/examples/echoserver.rst

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

doc/examples/geventsendfile.rst

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

doc/examples/index.rst

+==========
+ Examples
+==========
+
+..
+  All files generated with shell oneliner:
+  for i in examples/*py; do bn=`basename $i`; bnp=`basename $i .py`; echo -e "=============================\nExample $bn\n=============================\n.. literalinclude:: ../../examples/$bn\n  :language: python\n  :linenos:\n\n\`Current source <https://github.com/gevent/gevent/blob/master/examples/$bn>\`_\n" > doc/examples/$bnp.rst; done
+
+This is a snapshot of the examples contained in `the gevent source
+<https://github.com/gevent/gevent/tree/master/examples>`_.
+
+.. toctree::
+   concurrent_download
+   dns_mass_resolve
+   echoserver
+   geventsendfile
+   portforwarder
+   processes
+   psycopg2_pool
+   threadpool
+   udp_client
+   udp_server
+   unixsocket_client
+   unixsocket_server
+   webproxy
+   webpy
+   wsgiserver
+   wsgiserver_ssl

doc/examples/portforwarder.rst

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

doc/examples/processes.rst

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

doc/examples/psycopg2_pool.rst

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

doc/examples/threadpool.rst

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

doc/examples/udp_client.rst

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

doc/examples/udp_server.rst

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

doc/examples/unixsocket_client.rst

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

doc/examples/unixsocket_server.rst

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

doc/examples/webproxy.rst

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

doc/examples/webpy.rst

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

doc/examples/wsgiserver.rst

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

doc/examples/wsgiserver_ssl.rst

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

doc/intro.rst

@@ -133,7 +133,7 @@ in a multi-greenlet environment.
     >>> from gevent import monkey; monkey.patch_socket()
     >>> import urllib2 # it's usable from multiple greenlets now
 
-See `examples/concurrent_download.py`__
+See :doc:`examples/concurrent_download`.
 
 Beyond sockets
 --------------
@@ -159,7 +159,6 @@ modules using the :func:`gevent.monkey.patch_all` function::
    or sockets have been created, may lead to unpredictable
    results including unexpected :exc:`~gevent.hub.LoopExit` errors.
 
-__ https://github.com/gevent/gevent/blob/master/examples/concurrent_download.py#L1
 
 Event loop
 ==========
@@ -231,8 +230,8 @@ I/O functions that bypass the libev event loop.
 Synchronizing access to objects shared across the greenlets is
 unnecessary in most cases (because yielding control is usually
 explict), thus traditional synchronization devices like the
-:class:`~lock.BoundedSemaphore`, :class:`~lock.RLock` and
-:class:`~lock.Semaphore` classes, although present, aren't used very
+:class:`gevent.lock.BoundedSemaphore`, :class:`gevent.lock.RLock` and
+:class:`gevent.lock.Semaphore` classes, although present, aren't used very
 often. Other abstractions from threading and multiprocessing remain
 useful in the cooperative world:
 
@@ -244,9 +243,9 @@ useful in the cooperative world:
 Lightweight pseudothreads
 =========================
 
-.. currentmodule:: gevent.greenlet
+.. currentmodule:: gevent
 
-New greenlets are spawned by creating a :class:`~gevent.Greenlet` instance and calling its :meth:`start <gevent.Greenlet.start>`
+New greenlets are spawned by creating a :class:`~Greenlet` instance and calling its :meth:`start <gevent.Greenlet.start>`
 method. (The :func:`gevent.spawn` function is a shortcut that does exactly that). The :meth:`start <gevent.Greenlet.start>`
 method schedules a switch to the greenlet that will happen as soon as the current greenlet gives up control.
 If there is more than one active greenlet, they will be executed one
@@ -290,7 +289,7 @@ To subclass a :class:`gevent.Greenlet`, override its
             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:`~gevent.greenlet.GreenletExit` will be raised.
+of continuing execution, a :exc:`GreenletExit` will be raised.
 
     >>> g = MyNoopGreenlet(4)
     >>> g.start()
@@ -298,9 +297,9 @@ of continuing execution, a :exc:`~gevent.greenlet.GreenletExit` will be raised.
     >>> g.dead
     True
 
-The :exc:`gevent.greenlet.GreenletExit` exception and its subclasses are handled differently than other exceptions.
-Raising :exc:`~gevent.greenlet.GreenletExit` is not considered an exceptional situation, so the traceback is not printed.
-The :exc:`~gevent.greenlet.GreenletExit` is returned by :meth:`get <gevent.Greenlet.get>` as if it were returned by the greenlet, not raised.
+The :exc:`GreenletExit` exception and its subclasses are handled differently than other exceptions.
+Raising :exc:`~GreenletExit` is not considered an exceptional situation, so the traceback is not printed.
+The :exc:`~GreenletExit` is returned by :meth:`get <gevent.Greenlet.get>` as if it were returned by the greenlet, not raised.
 
 The :meth:`kill <gevent.Greenlet.kill>` method can accept a custom exception to be raised:
 
@@ -370,12 +369,10 @@ add timeouts to arbitrary sections of (cooperative, yielding) code.
 Further reading
 ===============
 
-To limit concurrency, use the :class:`gevent.pool.Pool` class (see `example: dns_mass_resolve.py`_).
+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`.
 
-.. _`example: dns_mass_resolve.py`: https://github.com/gevent/gevent/blob/master/examples/dns_mass_resolve.py#L17
-
 
 External resources
 ==================

doc/mytheme/layout.html

@@ -70,13 +70,6 @@
 
           {%- endif %}
           {%- endblock %}
-          {%- block sidebarrel %}
-          <h4 class="label label-orange">Related pages</h4>
-          <ul>
-          <li><a href="https://github.com/gevent/gevent/tree/master/examples"
-              title="Browse gevent/examples in the development repository">Code examples</a></li>
-          </ul>
-          {%- endblock %}
           {%- block sidebarsourcelink %}
           {%- if show_source and has_source and sourcename %}
             <h3>{{ _('This Page') }}</h3>

doc/servers.rst

@@ -41,20 +41,16 @@ server is stopped.
 
 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. Gunicorn has
-its own HTTP parser but can also use :mod:`gevent.wsgi` module.
+gunicorn_ is a stand-alone server that supports gevent.
 
-More examples are available in the `code repository`_:
+More :doc:`examples <examples/index>` are available:
+
+- :doc:`examples/echoserver` - demonstrates :class:`gevent.server.StreamServer`
+- :doc:`examples/wsgiserver` - demonstrates :class:`gevent.pywsgi.WSGIServer <gevent.pywsgi.WSGIServer>`
+- :doc:`examples/wsgiserver_ssl` - demonstrates :class:`WSGIServer with ssl <gevent.pywsgi.WSGIServer>`
 
-- `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`: https://github.com/gevent/gevent/tree/master/examples
 .. _gunicorn: http://gunicorn.org
-.. _`echoserver.py`: https://github.com/gevent/gevent/blob/master/examples/echoserver.py#L34
-.. _`wsgiserver.py`: https://github.com/gevent/gevent/blob/master/examples/wsgiserver.py#L18
-.. _`wsgiserver_ssl.py`: https://github.com/gevent/gevent/blob/master/examples/wsgiserver_ssl.py#L17
 
 .. toctree::
 

src/gevent/lock.py

@@ -201,6 +201,9 @@ class DummySemaphore(object):
 
 
 class RLock(object):
+    """
+    A mutex that can be acquired more than once by the same greenlet.
+    """
 
     def __init__(self):
         self._block = Semaphore(1)