[Docs] Change links to d.py docs to use pinned version instead of v1.0.1. (#3053)

* docs: change links to d.py docs to use stable version instead of v1.0.1

* chore(changelog): add towncrier entry

* docs: add |DPY_VERSION| substitution and :dpy_docs: role

* chore(changelog): update towncrier entries to reflect new changes

changelog.d/3053.docs.1.rst

@@ -0,0 +1 @@
+Discord.py docs links will now always use docs for currently used version of discord.py.

changelog.d/3053.docs.2.rst

@@ -0,0 +1 @@
+Add ``|DPY_VERSION|`` substitution that will automatically get replaced by current discord.py version.

docs/conf.py

@@ -36,6 +36,7 @@ os.environ["BUILDING_DOCS"] = "1"
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
@@ -65,6 +66,7 @@ author = "Cog Creators"
 # built documents.
 #
 from redbot.core import __version__
+from discord import __version__ as dpy_version
 
 # The short X.Y version.
 version = __version__
@@ -96,6 +98,9 @@ default_role = "any"
 with open("prolog.txt", "r") as file:
     rst_prolog = file.read()
 
+# Adds d.py version to available substitutions in all files
+rst_prolog = f"\n.. |DPY_VERSION| replace:: {dpy_version}"
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -209,10 +214,15 @@ linkcheck_ignore = [r"https://java.com*", r"https://chocolatey.org*"]
 # Intersphinx
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "dpy": ("https://discordpy.readthedocs.io/en/v1.0.1/", None),
+    "dpy": (f"https://discordpy.readthedocs.io/en/v{dpy_version}/", None),
     "motor": ("https://motor.readthedocs.io/en/stable/", None),
 }
 
+# Extlinks
+# This allows to create links to d.py docs with
+# :dpy_docs:`link text <site_name.html>`
+extlinks = {"dpy_docs": (f"https://discordpy.readthedocs.io/en/v{dpy_version}/%s", None)}
+
 # Doctest
 # If this string is non-empty, all blocks with ``>>>`` in them will be
 # tested, not just the ones explicitly marked with ``.. doctest::``

docs/guide_migration.rst

@@ -7,7 +7,7 @@
 Migrating Cogs to V3
 ====================
 
-First, be sure to read `discord.py's migration guide <https://discordpy.readthedocs.io/en/v1.0.1/migrating.html>`_
+First, be sure to read :dpy_docs:`discord.py's migration guide <migrating.html>`
 as that covers all of the changes to discord.py that will affect the migration process
 
 ----------------

docs/install_linux_mac.rst

@@ -314,5 +314,5 @@ Once done setting up the instance, run the following command to run Red:
 
 It will walk through the initial setup, asking for your token and a prefix.
 You can find out how to obtain a token with
-`this guide <https://discordpy.readthedocs.io/en/v1.0.1/discord.html#creating-a-bot-account>`_,
+:dpy_docs:`this guide <discord.html#creating-a-bot-account>`,
 section "Creating a Bot Account".

docs/install_windows.rst

@@ -119,5 +119,5 @@ Once done setting up the instance, run the following command to run Red:
 
 It will walk through the initial setup, asking for your token and a prefix.
 You can find out how to obtain a token with
-`this guide <https://discordpy.readthedocs.io/en/v1.0.1/discord.html#creating-a-bot-account>`_,
+:dpy_docs:`this guide <discord.html#creating-a-bot-account>`,
 section "Creating a Bot Account".