Correct links in DRY ReST documentation on Github, PyPi, and with Sphinx

README.rst

To write a dry overview with a link to another page in the documentation, use a substitution that replaces your text with a normal hyperlink that points to the correct page of the latest documentation on readthedocs, or wherever you host it.

overview.rst

..
   Using the include directive allows you to include the contents of the README
   without maintaining two copies of it. The substitution can be over-written
   so sphinx can provide a local link
   
.. include:: ../README.rst
.. |link_to_another_page| replace:: :doc:`link to another page<page>`

setup.py

from setuptools import setup, find_packages
from codecs import open
from os import path

here = path.abspath(path.dirname(__file__))

# get the version
exec(open('<project_name>/version.py').read())

# Get the long description from the README file
with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
    long_description = f.read()

# the links in the readme can be re-written to point at a particular
# version if desired
long_description = long_description.replace(
    "https://<project_name>.readthedocs.io/en/latest/",
    "https://<project_name>.readthedocs.io/en/<project_name>-{}/".format(
        '.'.join(__version__.split('.')[:3])
    )
)