Make the installation problems+solutions docs more prominent. [skip ci]

doc/intro.rst

@@ -43,8 +43,21 @@ without pre-built wheels or if wheel installation is disabled, a C compiler
 `cffi`_ can optionally be installed to build the CFFI backend in
 addition to the Cython backend on CPython.
 
+Development instructions can be found `on PyPI <https://pypi.python.org/pypi/gevent#development>`_.
+
+__ http://pypi.python.org/pypi/greenlet
+.. _`pip`: https://pip.pypa.io/en/stable/installing/
+.. _`wheels`: http://pythonwheels.com
+.. _`gevent 1.1`: whatsnew_1_1.html
+.. _`cffi`: https://cffi.readthedocs.io
+
+Common Installation Issues
+--------------------------
 
-.. tip:: Some Linux distributions are now mounting their temporary
+The following are some common installation problems and solutions for
+those compiling gevent from source.
+
+- Some Linux distributions are now mounting their temporary
   directories with the ``noexec`` option. This can cause a
   standard ``pip install gevent`` to fail with an error like
   ``cannot run C compiled programs``. One fix is to mount the
@@ -53,16 +66,15 @@ addition to the Cython backend on CPython.
   another directory. See :issue:`570` and :issue:`612` for
   examples.
 
-.. tip:: Also check for conflicts with environment variables like ``CFLAGS``. For
+- Also check for conflicts with environment variables like ``CFLAGS``. For
   example, see :ref:`library_updates_label`.
 
-Development instructions can be found `on PyPI <https://pypi.python.org/pypi/gevent#development>`_.
+- Users of a recent SmartOS release may need to customize
+  the ``CPPFLAGS`` (the environment variable containing the
+  default options for the C preprocessor) if they are using the
+  libev shipped with gevent. See :ref:`operating_systems_label` for
+  more information.
 
-__ http://pypi.python.org/pypi/greenlet
-.. _`pip`: https://pip.pypa.io/en/stable/installing/
-.. _`wheels`: http://pythonwheels.com
-.. _`gevent 1.1`: whatsnew_1_1.html
-.. _`cffi`: https://cffi.readthedocs.io
 
 Example
 =======

doc/whatsnew_1_1.rst

@@ -81,6 +81,8 @@ through 4.0.0 and 4.0.1, and on 32-bit ARM on Raspbian with version 4.0.1.
 .. _1.2.0: https://cffi.readthedocs.io/en/latest/whatsnew.html#v1-2-0
 .. _a bug: https://bitbucket.org/pypy/pypy/issues/2149/memory-leak-for-python-subclass-of-cpyext
 
+.. _operating_systems_label:
+
 Operating Systems
 -----------------