Revert removal of Python 2.7 in one commitThis is to make a release that supports Python 3.8 and Python 2.7. Thiscommit can be reverted to then remove 2.7 support again.

2 files changed, 33 insertions, 8 deletions

diff --git a/docs/conf.py b/docs/conf.py
index c1ea2ba..b746a90 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -49,9 +49,9 @@ source_suffix = ['.rst', '.md']
 master_doc = 'index'
 
 # General information about the project.
-project = 'natsort'
+project = u'natsort'
 # noinspection PyShadowingBuiltins
-copyright = '2014, Seth M. Morton'
+copyright = u'2014, Seth M. Morton'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -210,8 +210,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ('index', 'natsort.tex', 'natsort Documentation',
-     'Seth M. Morton', 'manual'),
+    ('index', 'natsort.tex', u'natsort Documentation',
+     u'Seth M. Morton', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -240,8 +240,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'natsort', 'natsort Documentation',
-     ['Seth M. Morton'], 1)
+    ('index', 'natsort', u'natsort Documentation',
+     [u'Seth M. Morton'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -254,8 +254,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    ('index', 'natsort', 'natsort Documentation',
-     'Seth M. Morton', 'natsort', 'One line description of project.',
+    ('index', 'natsort', u'natsort Documentation',
+     u'Seth M. Morton', 'natsort', 'One line description of project.',
      'Miscellaneous'),
 ]
 
diff --git a/docs/examples.rst b/docs/examples.rst
index 2c56a87..f09f8e5 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -314,6 +314,31 @@ need to pass a key to the :meth:`list.sort` method. The function
 :func:`~natsort_keygen` has the same API as :func:`~natsorted` (minus the
 `reverse` option).
 
+Natural Sorting with ``cmp`` (Python 2 only)
+--------------------------------------------
+
+.. note::
+    This is a Python2-only feature! The :func:`natcmp` function is not
+    exposed on Python3. Because this documentation is built with
+    Python3, you will not find :func:`natcmp` in the API.
+
+If you are using a legacy codebase that requires you to use :func:`cmp` instead
+of a key-function, you can use :func:`~natcmp`.
+
+.. code-block:: pycon
+
+    >>> import sys
+    >>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
+    >>> if sys.version_info[0] == 2:
+    ...     from natsort import natcmp
+    ...     sorted(a, cmp=natcmp)
+    ... else:
+    ...     natsorted(a)  # so docstrings don't fail
+    ['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
+
+:func:`natcmp` also accepts an ``alg`` argument so you can customize your
+sorting experience.
+
 Sorting Multiple Lists According to a Single List
 -------------------------------------------------