Mark special "__richcmp__()" method as deprecated in the docs.

Closes #1848.

docs/src/reference/extension_types.rst

@@ -279,9 +279,10 @@ Rich Comparisons
 * Starting with Cython 0.27, the Python
   `special methods <https://docs.python.org/3/reference/datamodel.html#basic-customization>`_
   ``__eq__``, ``__lt__``, etc. can be implemented.  In previous versions, ``__richcmp__`` was
-  the only way to implement rich comparisons.
+  the only way to implement rich comparisons, but is now deprecated.
 * A single special method called ``__richcmp__()`` can be used to implement all the individual
-  rich compare, special method types.
+  rich compare, special method types.  Note, however, that it is often easier to correctly
+  implement the separate Python special methods than to get the ``__richcmp__()`` method right.
 * ``__richcmp__()`` takes an integer argument, indicating which operation is to be performed
   as shown in the table below.
 

docs/src/userguide/special_methods.rst

@@ -209,8 +209,6 @@ Rich comparison operators
 
 https://docs.python.org/3/reference/datamodel.html#basic-customization
 
-+-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
-| __richcmp__           |x, y, int op                           | object      | Rich comparison (no direct Python equivalent)          |
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
 | __eq__                |self, y                                | object      | self == y                                              |
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
@@ -224,6 +222,12 @@ https://docs.python.org/3/reference/datamodel.html#basic-customization
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
 | __ge__                |self, y                                | object      | self >= y                                              |
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
+| __richcmp__           |x, y, int op                           | object      | Joined rich comparison method for all of the above     |
+|                       |                                       |             | (deprecated, no direct Python equivalent)              |
++-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
+
+New code should better implement the separate Python special methods instead of trying to
+correctly implement the joined ``__richcmp__()`` method.
 
 Arithmetic operators
 ^^^^^^^^^^^^^^^^^^^^