From 172dd58903f3f62271527d1b251ece7e3b590f24 Mon Sep 17 00:00:00 2001 From: jack1142 <6032823+jack1142@users.noreply.github.com> Date: Thu, 17 Oct 2019 13:58:39 +0200 Subject: [PATCH] [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 | 1 + changelog.d/3053.docs.2.rst | 1 + docs/conf.py | 12 +++++++++++- docs/guide_migration.rst | 2 +- docs/install_linux_mac.rst | 2 +- docs/install_windows.rst | 2 +- 6 files changed, 16 insertions(+), 4 deletions(-) create mode 100644 changelog.d/3053.docs.1.rst create mode 100644 changelog.d/3053.docs.2.rst diff --git a/changelog.d/3053.docs.1.rst b/changelog.d/3053.docs.1.rst new file mode 100644 index 000000000..c17689fc9 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/changelog.d/3053.docs.2.rst b/changelog.d/3053.docs.2.rst new file mode 100644 index 000000000..fa5f06b26 --- /dev/null +++ b/changelog.d/3053.docs.2.rst @@ -0,0 +1 @@ +Add ``|DPY_VERSION|`` substitution that will automatically get replaced by current discord.py version. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 98ba46e63..eb54c3f68 100644 --- a/docs/conf.py +++ b/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 ` +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::`` diff --git a/docs/guide_migration.rst b/docs/guide_migration.rst index c41009013..3d37f6c17 100644 --- a/docs/guide_migration.rst +++ b/docs/guide_migration.rst @@ -7,7 +7,7 @@ Migrating Cogs to V3 ==================== -First, be sure to read `discord.py's migration guide `_ +First, be sure to read :dpy_docs:`discord.py's migration guide ` as that covers all of the changes to discord.py that will affect the migration process ---------------- diff --git a/docs/install_linux_mac.rst b/docs/install_linux_mac.rst index ee37d80b2..a09f40723 100644 --- a/docs/install_linux_mac.rst +++ b/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 `_, +:dpy_docs:`this guide `, section "Creating a Bot Account". diff --git a/docs/install_windows.rst b/docs/install_windows.rst index 6d003ca6f..3cea6d5ae 100644 --- a/docs/install_windows.rst +++ b/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 `_, +:dpy_docs:`this guide `, section "Creating a Bot Account".