Improve link handling in README.rst

1 files changed, 115 insertions, 92 deletions

diff --git a/README.rst b/README.rst
index f4639b1..79ed3ae 100644
--- a/README.rst
+++ b/README.rst
@@ -22,9 +22,9 @@ Simple yet flexible natural sorting in Python.
     - Downloads: https://pypi.org/project/natsort/
     - Documentation: https://natsort.readthedocs.io/
 
-      - `Examples and Recipes <https://natsort.readthedocs.io/en/master/examples.html>`_
-      - `How Does Natsort Work? <https://natsort.readthedocs.io/en/master/howitworks.html>`_
-      - `API <https://natsort.readthedocs.io/en/master/api.html>`_
+      - `Examples and Recipes`_
+      - `How Does Natsort Work?`_
+      - `API`_
 
     - `Quick Description`_
     - `Quick Examples`_
@@ -56,10 +56,10 @@ Notice that it has the order ('1', '10', '2') - this is because the list is
 being sorted in lexicographical order, which sorts numbers like you would
 letters (i.e. 'b', 'ba', 'c').
 
-``natsort`` provides a function ``natsorted`` that helps sort lists
+`natsort`_ provides a function `natsorted()`_ that helps sort lists
 "naturally" ("naturally" is rather ill-defined, but in general it means
 sorting based on meaning and not computer code point).
-Using ``natsorted`` is simple:
+Using `natsorted()`_ is simple:
 
 .. code-block:: pycon
 
@@ -68,14 +68,13 @@ Using ``natsorted`` is simple:
     >>> natsorted(a)
     ['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
 
-``natsorted`` identifies numbers anywhere in a string and sorts them
-naturally. Below are some other things you can do with ``natsort``
-(also see the `examples <https://natsort.readthedocs.io/en/master/examples.html>`_
-for a quick start guide, or the
-`api <https://natsort.readthedocs.io/en/master/api.html>`_ for complete details).
+`natsorted()`_ identifies numbers anywhere in a string and sorts them
+naturally. Below are some other things you can do with `natsort`_
+(also see the `Examples and Recipes`_for a quick start guide, or the
+` API`_ for complete details).
 
-**Note**: ``natsorted`` is designed to be a drop-in replacement for the
-built-in ``sorted`` function. Like ``sorted``, ``natsorted``
+**Note**: `natsorted()`_ is designed to be a drop-in replacement for the
+built-in `sorted()`_ function. Like `sorted()`_, `natsorted()`_
 `does not sort in-place`. To sort a list and assign the output to the same
 variable, you must explicitly assign the output to a variable:
 
@@ -109,12 +108,12 @@ Quick Examples
 Sorting Versions
 ++++++++++++++++
 
-``natsort`` does not actually *comprehend* version numbers.
+`natsort`_ does not actually *comprehend* version numbers.
 It just so happens that the most common versioning schemes are designed to
 work with standard natural sorting techniques; these schemes include
 ``MAJOR.MINOR``, ``MAJOR.MINOR.PATCH``, ``YEAR.MONTH.DAY``. If your data
 conforms to a scheme like this, then it will work out-of-the-box with
-``natsorted`` (as of ``natsort`` version >= 4.0.0):
+`natsorted()`_ (as of `natsort`_ version >= 4.0.0):
 
 .. code-block:: pycon
 
@@ -123,14 +122,14 @@ conforms to a scheme like this, then it will work out-of-the-box with
     ['version-1.9', 'version-1.10', 'version-1.11', 'version-2.0']
 
 If you need to versions that use a more complicated scheme, please see
-`these examples <https://natsort.readthedocs.io/en/master/examples.html#rc-sorting>`_.
+`these version sorting examples`_.
 
 Sort Paths Like My File Browser (e.g. Windows Explorer on Windows)
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Prior to ``natsort`` version 7.1.0, it was a common request to be able to
-sort paths like Windows Explorer. As of ``natsort`` 7.1.0, the function
-``os_sorted`` has been added to provide users the ability to sort
+Prior to `natsort`_ version 7.1.0, it was a common request to be able to
+sort paths like Windows Explorer. As of `natsort`_ 7.1.0, the function
+`os_sorted()`_ has been added to provide users the ability to sort
 in the order that their file browser might sort (e.g Windows Explorer on
 Windows, Finder on MacOS, Dolphin/Nautilus/Thunar/etc. on Linux).
 
@@ -144,17 +143,17 @@ Windows, Finder on MacOS, Dolphin/Nautilus/Thunar/etc. on Linux).
 Output will be different depending on the operating system you are on.
 
 For users **not** on Windows (e.g. MacOS/Linux) it is **strongly** recommended
-to also install `PyICU <https://pypi.org/project/PyICU>`_, which will help
-``natsort`` give results that match most file browsers. If this is not installed,
-it will fall back on Python's built-in ``locale`` module and will give good
+to also install `PyICU`_, which will help
+`natsort`_ give results that match most file browsers. If this is not installed,
+it will fall back on Python's built-in `locale`_ module and will give good
 results for most input, but will give poor results for special characters.
 
 Sorting by Real Numbers (i.e. Signed Floats)
 ++++++++++++++++++++++++++++++++++++++++++++
 
-This is useful in scientific data analysis (and was
-the default behavior of ``natsorted`` for ``natsort``
-version < 4.0.0). Use the ``realsorted`` function:
+This is useful in scientific data analysis (and was the default behavior
+of `natsorted()`_ for `natsort`_ version < 4.0.0). Use the `realsorted()`_
+function:
 
 .. code-block:: pycon
 
@@ -175,7 +174,7 @@ Locale-Aware Sorting (or "Human Sorting")
 This is where the non-numeric characters are also ordered based on their
 meaning, not on their ordinal value, and a locale-dependent thousands
 separator and decimal separator is accounted for in the number.
-This can be achieved with the ``humansorted`` function:
+This can be achieved with the `humansorted()`_ function:
 
 .. code-block:: pycon
 
@@ -192,9 +191,8 @@ This can be achieved with the ``humansorted`` function:
     ['apple15', 'apple14,689', 'Apple', 'banana', 'Banana']
 
 You may find you need to explicitly set the locale to get this to work
-(as shown in the example).
-Please see `locale issues <https://natsort.readthedocs.io/en/master/locale_issues.html>`_ and the
-`Optional Dependencies`_ section below before using the ``humansorted`` function.
+(as shown in the example). Please see `locale issues`_ and the
+`Optional Dependencies`_ section below before using the `humansorted()`_ function.
 
 Further Customizing Natsort
 +++++++++++++++++++++++++++
@@ -218,7 +216,7 @@ bitwise OR operator (``|``). For example,
     True
 
 All of the available customizations can be found in the documentation for
-`the ns enum <https://natsort.readthedocs.io/en/master/api.html#natsort.ns>`_.
+`the ns enum`_.
 
 You can also add your own custom transformation functions with the ``key``
 argument. These can be used with ``alg`` if you wish.
@@ -232,8 +230,7 @@ argument. These can be used with ``alg`` if you wish.
 Sorting Mixed Types
 +++++++++++++++++++
 
-You can mix and match ``int``, ``float``, and ``str`` (or ``unicode``) types
-when you sort:
+You can mix and match `int`_, `float`_, and `str`_ types when you sort:
 
 .. code-block:: pycon
 
@@ -245,8 +242,8 @@ when you sort:
 Handling Bytes
 ++++++++++++++
 
-``natsort`` does not officially support the `bytes` type, but
-convenience functions are provided that help you decode to `str` first:
+`natsort`_ does not officially support the `bytes`_ type, but
+convenience functions are provided that help you decode to `str`_ first:
 
 .. code-block:: pycon
 
@@ -263,10 +260,10 @@ convenience functions are provided that help you decode to `str` first:
 Generating a Reusable Sorting Key and Sorting In-Place
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Under the hood, ``natsorted`` works by generating a custom sorting
-key using ``natsort_keygen`` and then passes that to the built-in
-``sorted``. You can use the ``natsort_keygen`` function yourself to
-generate a custom sorting key to sort in-place using the ``list.sort``
+Under the hood, `natsorted()`_ works by generating a custom sorting
+key using `natsort_keygen()`_ and then passes that to the built-in
+`sorted()`_. You can use the `natsort_keygen()`_ function yourself to
+generate a custom sorting key to sort in-place using the `list.sort()`_
 method.
 
 .. code-block:: pycon
@@ -282,53 +279,49 @@ method.
 
 All of the algorithm customizations mentioned in the
 `Further Customizing Natsort`_ section can also be applied to
-``natsort_keygen`` through the *alg* keyword option.
+`natsort_keygen()`_ through the *alg* keyword option.
 
 Other Useful Things
 +++++++++++++++++++
 
  - recursively descend into lists of lists
  - automatic unicode normalization of input data
- - `controlling the case-sensitivity <https://natsort.readthedocs.io/en/master/examples.html#case-sort>`_
- - `sorting file paths correctly <https://natsort.readthedocs.io/en/master/examples.html#path-sort>`_
- - `allow custom sorting keys <https://natsort.readthedocs.io/en/master/examples.html#custom-sort>`_
- - `accounting for units <https://natsort.readthedocs.io/en/master/examples.html#accounting-for-units-when-sorting>`_
+ - `controlling the case-sensitivity`_
+ - `sorting file paths correctly`_
+ - `allow custom sorting keys`_
+ - `accounting for units`_
 
 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
+How do I debug `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? <https://natsort.readthedocs.io/en/master/howitworks.html>`_
-    page for *why* ``natsort`` is doing that to your data.
+    recommended to `look at this issue describing how to debug`_ for *how* to debug,
+    and also to review the `How Does Natsort Work?`_ 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
+    `natsort`_, or use the `natsort`_ key as part of your rich comparison
     operator definition.
 
-``natsort`` gave me results I didn't expect, and it's a terrible library!
+`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>`_.
+    the error, then please `file an issue`_.
 
-How *does* ``natsort`` work?
-    If you don't want to read `How Does Natsort Work? <https://natsort.readthedocs.io/en/master/howitworks.html>`_,
+How *does* `natsort`_ work?
+    If you don't want to read `How Does Natsort Work?`_,
     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:
+    `natsort`_ provides a `key function`_ that can be passed to `list.sort()`_
+    or `sorted()`_ in order to modify the default sorting behavior. This key
+    is generated on-demand with the key generator `natsort.natsort_keygen()`_.
+    `natsorted()_` is essentially a wrapper for the following code:
 
     .. code-block:: pycon
 
@@ -337,35 +330,35 @@ How *does* ``natsort`` work?
         >>> sorted(['1', '10', '2'], key=natsort_key)
         ['1', '2', '10']
 
-    Users can further customize ``natsort`` sorting behavior with the ``key``
+    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
+    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``.
+         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
+         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``.
+         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``.
+    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`_.
 
 Shell script
 ------------
 
-``natsort`` comes with a shell script called ``natsort``, or can also be called
+`natsort`_ comes with a shell script called `natsort`_, or can also be called
 from the command line with ``python -m natsort``.
 
 Requirements
 ------------
 
-``natsort`` requires Python 3.7 or greater.
+`natsort`_ requires Python 3.7 or greater.
 
 Optional Dependencies
 ---------------------
@@ -374,20 +367,18 @@ fastnumbers
 +++++++++++
 
 The most efficient sorting can occur if you install the
-`fastnumbers <https://pypi.org/project/fastnumbers>`_ package
+`fastnumbers>`_ package
 (version >=2.0.0); it helps with the string to number conversions.
-``natsort`` will still run (efficiently) without the package, but if you need
+`natsort`_ will still run (efficiently) without the package, but if you need
 to squeeze out that extra juice it is recommended you include this as a
-dependency. ``natsort`` will not require (or check) that
-`fastnumbers <https://pypi.org/project/fastnumbers>`_ is installed
-at installation.
+dependency. `natsort`_ will not require (or check) that
+`fastnumbers>`_ is installed at installation.
 
 PyICU
 +++++
 
-It is recommended that you install `PyICU <https://pypi.org/project/PyICU>`_
-if you wish to sort in a locale-dependent manner, see
-https://natsort.readthedocs.io/en/master/locale_issues.html for an explanation why.
+It is recommended that you install `PyICU`_ if you wish to sort in a
+locale-dependent manner, see this page on `locale issues`_ for an explanation why.
 
 Installation
 ------------
@@ -399,10 +390,8 @@ Use ``pip``!
     $ pip install natsort
 
 If you want to install the `Optional Dependencies`_, you can use the
-`"extras" notation <https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras>`_
-at installation time to install those dependencies as well - use ``fast`` for
-`fastnumbers <https://pypi.org/project/fastnumbers>`_ and ``icu`` for
-`PyICU <https://pypi.org/project/PyICU>`_.
+`"extras" notation`_ at installation time to install those dependencies as
+well - use ``fast`` for `fastnumbers>`_ and ``icu`` for `PyICU`_.
 
 .. code-block:: console
 
@@ -414,11 +403,10 @@ at installation time to install those dependencies as well - use ``fast`` for
 How to Run Tests
 ----------------
 
-Please note that ``natsort`` is NOT set-up to support ``python setup.py test``.
+Please note that `natsort`_ is NOT set-up to support ``python setup.py test``.
 
-The recommended way to run tests is with `tox <https://tox.readthedocs.io/en/latest/>`_.
-After installing ``tox``, running tests is as simple as executing the following
-in the ``natsort`` directory:
+The recommended way to run tests is with `tox`_. After installing ``tox``,
+running tests is as simple as executing the following in the `natsort`_ directory:
 
 .. code-block:: console
 
@@ -433,7 +421,7 @@ with ``tox --listenvs``.
 How to Build Documentation
 --------------------------
 
-If you want to build the documentation for ``natsort``, it is recommended to
+If you want to build the documentation for `natsort`_, it is recommended to
 use ``tox``:
 
 .. code-block:: console
@@ -445,7 +433,7 @@ This will place the documentation in ``build/sphinx/html``.
 Dropped Deprecated APIs
 -----------------------
 
-In ``natsort`` version 6.0.0, the following APIs and functions were removed
+In `natsort`_ version 6.0.0, the following APIs and functions were removed
 
  - ``number_type`` keyword argument (deprecated since 3.4.0)
  - ``signed`` keyword argument (deprecated since 3.4.0)
@@ -467,7 +455,7 @@ can run your code with the following flag
 
     $ python -Wdefault::DeprecationWarning my-code.py
 
-By default ``DeprecationWarnings`` are not shown, but this will cause them
+By default `DeprecationWarnings`_ are not shown, but this will cause them
 to be shown. Alternatively, you can just set the environment variable
 ``PYTHONWARNINGS`` to "default::DeprecationWarning" and then run your code.
 
@@ -479,6 +467,41 @@ Seth M. Morton
 History
 -------
 
-Please visit the changelog
-`on GitHub <https://github.com/SethMMorton/natsort/blob/master/CHANGELOG.md>`_ or
-`in the documentation <https://natsort.readthedocs.io/en/master/changelog.html>`_.
+Please visit the changelog `on GitHub`_ or `in the documentation`_.
+
+.. _natsort: https://natsort.readthedocs.io/en/stable/index.html
+.. _natsorted(): https://natsort.readthedocs.io/en/stable/api.html#natsort.natsorted
+.. _natsort_keygen(): https://natsort.readthedocs.io/en/stable/api.html#natsort.natsort_keygen
+.. _realsorted(): https://natsort.readthedocs.io/en/stable/api.html#natsort.realsorted
+.. _humansorted(): https://natsort.readthedocs.io/en/stable/api.html#natsort.humansorted
+.. _os_sorted(): https://natsort.readthedocs.io/en/stable/api.html#natsort.os_sorted
+.. _the ns enum: https://natsort.readthedocs.io/en/stable/api.html#natsort.ns
+.. _fastnumbers: https://github.com/SethMMorton/fastnumbers
+.. _sorted(): https://docs.python.org/3/library/functions.html#sorted
+.. _list.sort(): https://docs.python.org/3/library/stdtypes.html#list.sort
+.. _key function: https://docs.python.org/3/howto/sorting.html#key-functions
+.. _locale: https://docs.python.org/3/library/locale.html
+.. _int: https://docs.python.org/3/library/functions.html#int
+.. _float: https://docs.python.org/3/library/functions.html#float
+.. _str: https://docs.python.org/3/library/stdtypes.html#str
+.. _bytes: https://docs.python.org/3/library/stdtypes.html#bytes
+.. _list: https://docs.python.org/3/library/stdtypes.html#list
+.. _tuple: https://docs.python.org/3/library/stdtypes.html#tuple
+.. _TypeError: https://docs.python.org/3/library/exceptions.html#TypeError
+.. _DeprecationWarnings: https://docs.python.org/3/library/exceptions.html#DeprecationWarning
+.. _"extras" notation" https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras
+.. _PyICU: https://pypi.org/project/PyICU
+.. _tox: https://tox.readthedocs.io/en/latest/
+.. _Examples and Recipes: https://natsort.readthedocs.io/en/stable/examples.html
+.. _How Does Natsort Work?: https://natsort.readthedocs.io/en/stable/howitworks.html
+.. _API: https://natsort.readthedocs.io/en/stable/api.html
+.. _on GitHub: https://github.com/SethMMorton/natsort/blob/master/CHANGELOG.md
+.. _in the documentation: https://natsort.readthedocs.io/en/stable/changelog.html
+.. _file an issue: https://github.com/SethMMorton/natsort/issues/new
+.. _look at this issue describing how to debug: https://github.com/SethMMorton/natsort/issues/13#issuecomment-50422375
+.. _controlling the case-sensitivity: https://natsort.readthedocs.io/en/stable/examples.html#case-sort
+.. _sorting file paths correctly: https://natsort.readthedocs.io/en/stable/examples.html#path-sort
+.. _allow custom sorting keys: https://natsort.readthedocs.io/en/stable/examples.html#custom-sort
+.. _accounting for units: https://natsort.readthedocs.io/en/stable/examples.html#accounting-for-units-when-sorting
+.. _these version sorting examples: https://natsort.readthedocs.io/en/stable/examples.html#rc-sorting
+.. _locale issues: https://natsort.readthedocs.io/en/stable/locale_issues.html
\ No newline at end of file