Skip to content

Instantly share code, notes, and snippets.

Last active September 17, 2017 14:12
What would you like to do?
Correct links in DRY ReST documentation on Github, PyPi, and with Sphinx

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.

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>`
from setuptools import setup, find_packages
from codecs import open
from os import path
here = path.abspath(path.dirname(__file__))
# get the version
# Get the long description from the README file
with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
long_description =
# the links in the readme can be re-written to point at a particular
# version if desired
long_description = long_description.replace(
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment