Create a FAQ section in the README/intro.

This holds the previously created "How it works" section.

2 files changed, 121 insertions, 103 deletions

diff --git a/README.rst b/README.rst
index e4db822..b384dc7 100644
--- a/README.rst
+++ b/README.rst
@@ -33,6 +33,7 @@ Simple yet flexible natural sorting in Python.
         `this post <https://opensource.stackexchange.com/q/5941/8999>`_ for an
         explanation into why.
 
+    - `FAQ`_
     - `Optional Dependencies`_
 
       - `fastnumbers <https://pypi.org/project/fastnumbers>`_ >= 2.0.0
@@ -92,51 +93,6 @@ explicitly assign the output to a variable:
 Please see `Generating a Reusable Sorting Key and Sorting In-Place`_ for
 an alternate way to sort in-place naturally.
 
-How It Works
-------------
-
-**NOTE**: For a complete description of how ``natsort`` works, please visit
-`How Does Natsort Work? <http://natsort.readthedocs.io/en/master/howitworks.html>`_.
-
-``natsort`` exposes a `key function <https://docs.python.org/3/howto/sorting.html#key-functions>`_
-that can be passed to `list.sort() <https://docs.python.org/3/library/stdtypes.html#list.sort>`_
-or `sorted() <https://docs.python.org/3/library/functions.html#sorted>`_ in order to
-modify the default sorting behavior. This key is generated on-demand with the
-key generator ``natsort.natsort_keygen()``.  ``natsort.natsorted()`` is essentially
-a wrapper for the following code:
-
-.. code-block:: python
-
-    >>> from natsort import natsort_keygen
-    >>> natsort_key = natsort_keygen()
-    >>> sorted(['1', '10', '2'], key=natsort_key)
-    ['1', '2', '10']
-
-Users can further customize ``natsort`` sorting behavior with the ``key``
-and/or ``alg`` options (see details in the `Further Customizing Natsort`_
-section).
-
-The key generated by ``natsort_keygen`` *always* returns a ``tuple``. It
-does so in the following way (*some details omitted for clarity*):
-
-  1. Assume the input is a string, and attempt to split it into numbers and
-     non-numbers using regular expressions. Numbers are then converted into
-     either ``int`` or ``float``.
-  2. If the above fails because the input is not a string, assume the input
-     is some other sequence (e.g. ``list`` or ``tuple``), and recursively
-     apply the key to each element of the sequence.
-  3. If the above fails because the input is not iterable, assume the input
-     is an ``int`` or ``float``, and just return the input in a ``tuple``.
-
-Because a ``tuple`` is always returned, a ``TypeError`` should not be common
-unless one tries to do something odd like sort an ``int`` against a ``list``.
-**NOTE**: Custom classes are not likely to be sorted correctly if one relies
-on the behavior of ``__lt__`` and the other rich comparison operators in their
-custom class - it is better to use a ``key`` function with ``natsort``, or
-use the ``natsort`` key as part of your rich comparison operator definition
-(please see https://github.com/SethMMorton/natsort/issues/60 for details and
-solutions).
-
 Examples
 --------
 
@@ -300,6 +256,66 @@ Other Useful Things
  - `sorting file paths correctly <http://natsort.readthedocs.io/en/master/examples.html#path-sort>`_
  - `allow custom sorting keys <http://natsort.readthedocs.io/en/master/examples.html#custom-sort>`_
 
+FAQ
+---
+
+How do I debug ``natsort.natsorted()``?
+    The best way to debug ``natsorted()`` is to generate a key using ``natsort_keygen()``
+    with the same options being passed to ``natsorted``. One can take a look at
+    exactly what is being done with their input using this key - it is highly recommended
+    to `look at this issue describing how to debug <https://github.com/SethMMorton/natsort/issues/13#issuecomment-50422375>`_
+    for *how* to debug, and also to review the
+    `How Does Natsort Work? <http://natsort.readthedocs.io/en/master/howitworks.html>`_
+    page for *why* ``natsort`` is doing that to your data.
+
+    If you are trying to sort custom classes and running into trouble, please take a look at
+    https://github.com/SethMMorton/natsort/issues/60. In short,
+    custom classes are not likely to be sorted correctly if one relies
+    on the behavior of ``__lt__`` and the other rich comparison operators in their
+    custom class - it is better to use a ``key`` function with ``natsort``, or
+    use the ``natsort`` key as part of your rich comparison operator definition.
+
+How *does* ``natsort`` work?
+    If you don't want to read `How Does Natsort Work? <http://natsort.readthedocs.io/en/master/howitworks.html>`_,
+    here is a quick primer.
+
+    ``natsort`` provides a `key function <https://docs.python.org/3/howto/sorting.html#key-functions>`_
+    that can be passed to `list.sort() <https://docs.python.org/3/library/stdtypes.html#list.sort>`_
+    or `sorted() <https://docs.python.org/3/library/functions.html#sorted>`_ in order to
+    modify the default sorting behavior. This key is generated on-demand with the
+    key generator ``natsort.natsort_keygen()``.  ``natsort.natsorted()`` is essentially
+    a wrapper for the following code:
+
+    .. code-block:: python
+
+        >>> from natsort import natsort_keygen
+        >>> natsort_key = natsort_keygen()
+        >>> sorted(['1', '10', '2'], key=natsort_key)
+        ['1', '2', '10']
+
+    Users can further customize ``natsort`` sorting behavior with the ``key``
+    and/or ``alg`` options (see details in the `Further Customizing Natsort`_
+    section).
+
+    The key generated by ``natsort_keygen`` *always* returns a ``tuple``. It
+    does so in the following way (*some details omitted for clarity*):
+
+      1. Assume the input is a string, and attempt to split it into numbers and
+         non-numbers using regular expressions. Numbers are then converted into
+         either ``int`` or ``float``.
+      2. If the above fails because the input is not a string, assume the input
+         is some other sequence (e.g. ``list`` or ``tuple``), and recursively
+         apply the key to each element of the sequence.
+      3. If the above fails because the input is not iterable, assume the input
+         is an ``int`` or ``float``, and just return the input in a ``tuple``.
+
+    Because a ``tuple`` is always returned, a ``TypeError`` should not be common
+    unless one tries to do something odd like sort an ``int`` against a ``list``.
+
+``natsort`` gave me results I didn't expect, and it's a terrible library!
+    Did you try to debug using the above advice? If so, and you still cannot figure out
+    the error, then please `file an issue <https://github.com/SethMMorton/natsort/issues/new>`_.
+
 Shell script
 ------------
 
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index 1bfb74a..91ce343 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -9,15 +9,6 @@ Simple yet flexible natural sorting in Python.
     - Source Code: https://github.com/SethMMorton/natsort
     - Downloads: https://pypi.org/project/natsort/
     - Documentation: http://natsort.readthedocs.io/
-
-      - :ref:`Examples and Recipes <examples>`
-      - :ref:`How Does Natsort Work? <howitworks>`
-      - :ref:`API <api>`
-      - **NOTE**: The old documentation at pythonhosted.org has been taken down
-        with no redirects. Please see
-        `this post <https://opensource.stackexchange.com/q/5941/8999>`_ for an
-        explanation into why.
-
     - Optional Dependencies:
 
       - `fastnumbers <https://pypi.org/project/fastnumbers>`_ >= 2.0.0
@@ -96,55 +87,6 @@ for more details).
     Please see `Generating a Reusable Sorting Key and Sorting In-Place`_ for
     an alternate way to sort in-place naturally.
 
-How It Works
-------------
-
-.. note::
-    For a complete description of how ``natsort`` works, please visit
-    `How Does Natsort Work? <http://natsort.readthedocs.io/en/master/howitworks.html>`_.
-
-:mod:`natsort` exposes a `key function <https://docs.python.org/3/howto/sorting.html#key-functions>`_
-that can be passed to `list.sort() <https://docs.python.org/3/library/stdtypes.html#list.sort>`_
-or `sorted() <https://docs.python.org/3/library/functions.html#sorted>`_ in order to
-modify the default sorting behavior. This key is generated on-demand with the
-key generator :func:`natsort.natsort_keygen`.  :func:`natsort.natsorted` is essentially
-a wrapper for the following code:
-
-.. code-block:: python
-
-    >>> from natsort import natsort_keygen
-    >>> natsort_key = natsort_keygen()
-    >>> sorted(['1', '10', '2'], key=natsort_key)
-    ['1', '2', '10']
-
-Users can further customize :mod:`natsort` sorting behavior with the ``key``
-and/or ``alg`` options (see details in the `Further Customizing Natsort`_
-section).
-
-The key generated by :func:`natsort.natsort_keygen` *always* returns a ``tuple``. It
-does so in the following way (*some details omitted for clarity*):
-
-  1. Assume the input is a string, and attempt to split it into numbers and
-     non-numbers using regular expressions. Numbers are then converted into
-     either ``int`` or ``float``.
-  2. If the above fails because the input is not a string, assume the input
-     is some other sequence (e.g. ``list`` or ``tuple``), and recursively
-     apply the key to each element of the sequence.
-  3. If the above fails because the input is not iterable, assume the input
-     is an ``int`` or ``float``, and just return the input in a ``tuple``.
-
-Because a ``tuple`` is always returned, a ``TypeError`` should not be common
-unless one tries to do something odd like sort an ``int`` against a ``list``.
-
-.. note::
-
-    Custom classes are not likely to be sorted correctly if one relies
-    on the behavior of ``__lt__`` and the other rich comparison operators in their
-    custom class - it is better to use a ``key`` function with :mod:`natsort`, or
-    use the :mod:`natsort` key as part of your rich comparison operator definition
-    (please see https://github.com/SethMMorton/natsort/issues/60 for details and
-    solutions).
-
 Examples
 --------
 
@@ -308,6 +250,66 @@ Other Useful Things
  - sorting file paths correctly (see :ref:`path_sort`)
  - allow custom sorting keys (see :ref:`custom_sort`)
 
+FAQ
+---
+
+How do I debug :func:`~natsorted`?
+    The best way to debug :func:`~natsorted` is to generate a key using :func:`~natsort_keygen`
+    with the same options being passed to :func:`~natsorted`. One can take a look at
+    exactly what is being done with their input using this key - it is highly recommended
+    to `look at this issue describing how to debug <https://github.com/SethMMorton/natsort/issues/13#issuecomment-50422375>`_
+    for *how* to debug, and also to review the
+    `How Does Natsort Work? <http://natsort.readthedocs.io/en/master/howitworks.html>`_
+    page for *why* :mod:`natsort` is doing that to your data.
+
+    If you are trying to sort custom classes and running into trouble, please take a look at
+    https://github.com/SethMMorton/natsort/issues/60. In short,
+    custom classes are not likely to be sorted correctly if one relies
+    on the behavior of ``__lt__`` and the other rich comparison operators in their
+    custom class - it is better to use a ``key`` function with :mod:`natsort`, or
+    use the :mod:`natsort` key as part of your rich comparison operator definition.
+
+How *does* :mod:`natsort` work?
+    If you don't want to read `How Does Natsort Work? <http://natsort.readthedocs.io/en/master/howitworks.html>`_,
+    here is a quick primer.
+
+    :mod:`natsort` provides a `key function <https://docs.python.org/3/howto/sorting.html#key-functions>`_
+    that can be passed to `list.sort() <https://docs.python.org/3/library/stdtypes.html#list.sort>`_
+    or `sorted() <https://docs.python.org/3/library/functions.html#sorted>`_ in order to
+    modify the default sorting behavior. This key is generated on-demand with the
+    key generator :func:`natsort.natsort_keygen`.  :func:`natsort.natsorted` is essentially
+    a wrapper for the following code:
+
+    .. code-block:: python
+
+        >>> from natsort import natsort_keygen
+        >>> natsort_key = natsort_keygen()
+        >>> sorted(['1', '10', '2'], key=natsort_key)
+        ['1', '2', '10']
+
+    Users can further customize :mod:`natsort` sorting behavior with the ``key``
+    and/or ``alg`` options (see details in the `Further Customizing Natsort`_
+    section).
+
+    The key generated by :func:`natsort.natsort_keygen` *always* returns a :class:`tuple`. It
+    does so in the following way (*some details omitted for clarity*):
+
+      1. Assume the input is a string, and attempt to split it into numbers and
+         non-numbers using regular expressions. Numbers are then converted into
+         either :class:`int` or :class:`float`.
+      2. If the above fails because the input is not a string, assume the input
+         is some other sequence (e.g. :class:`list` or :class:`tuple`), and recursively
+         apply the key to each element of the sequence.
+      3. If the above fails because the input is not iterable, assume the input
+         is an :class:`int` or :class:`float`, and just return the input in a :class:`tuple`.
+
+    Because a :class:`tuple` is always returned, a :exc:`TypeError` should not be common
+    unless one tries to do something odd like sort an :class:`int` against a :class:`list`.
+
+:mod:`natsort` gave me results I didn't expect, and it's a terrible library!
+    Did you try to debug using the above advice? If so, and you still cannot figure out
+    the error, then please `file an issue <https://github.com/SethMMorton/natsort/issues/new>`_.
+
 Shell script
 ------------