Skip to content

Instantly share code, notes, and snippets.

@sixpearls
Last active September 17, 2017 14:12
Show Gist options
  • Save sixpearls/e5d583d91e6492cf304655e2f0ecb8d8 to your computer and use it in GitHub Desktop.
Save sixpearls/e5d583d91e6492cf304655e2f0ecb8d8 to your computer and use it in GitHub Desktop.
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
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])
)
)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment