Add document on caveats and known issues.

Fixes #143.

docs/caveats.rst

@@ -0,0 +1,34 @@
+==========================
+ Caveats and Known Issues
+==========================
+
+This document will describe known issues and sharp edges of greenlets.
+
+
+Native Functions Should Be Re-entrant
+=====================================
+
+Use caution when switching greenlet stacks that include native (C)
+frames. Much like with threads, if the library function is not
+re-entrant, and more than one greenlet attempts to enter it, subtle
+problems can result.
+
+Common constructs in C that may not be reentrant include:
+
+- static variables in functions;
+- global variables.
+
+This was the source of an issue in gevent that led to corruption of
+libuv's internal state. The fix was to avoid re-entering the
+vulnerable function.
+
+Use Caution Mixing Greenlets and Signal Handlers
+================================================
+
+In CPython, signal handler functions *must* return in order for the
+rest of the program to proceed. Switching greenlets in a signal
+handler to, for example, get back to the main greenlet, such that the
+signal handler function doesn't really return to CPython, is likely to
+lead to a hang.
+
+See :issue:`143` for an example.

docs/conf.py

@@ -32,6 +32,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
+    'sphinx.ext.extlinks',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
  ]
@@ -267,3 +268,10 @@
 }
 autodoc_member_order = 'bysource'
 autoclass_content = 'both'
+
+extlinks = {
+    'issue': ('https://github.com/python-greenlet/greenlet/issues/%s',
+              'issue #'),
+    'pr': ('https://github.com/python-greenlet/greenlet/pull/%s',
+           'pull request #')
+}

docs/index.rst

@@ -53,6 +53,7 @@
       contextvars
       greenlet_gc
       tracing
+      caveats
 
 .. rubric:: What are greenlets?