Restore Releases Changelog

Add the releases-based changelog system back, and migrate the old
changelog entries.

Signed-off-by: Hassan Abouelela <[email protected]>

7 files changed, 246 insertions, 9 deletions

diff --git a/docs/README.md b/docs/README.md
index fa719292..2146ce5b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -38,11 +38,11 @@ Refer to the [sphinx documentation][docstring-sections] for more information.
 Each change requires an entry in the [Changelog](./changelog.rst).
 
 Refer to the [Releases][releases] documentation for more information on the exact format and content of entries
-You can use [this site][releases] to get the PR number you'll use for your entry.
+You can use [this site][next] to get the PR number that'll be assigned for your entry.
 
 
-[next]: https://ichard26.github.io/next-pr-number/?owner=python-discord&name=bot-core
 [releases]: https://releases.readthedocs.io/en/latest/concepts.html
+[next]: https://ichard26.github.io/next-pr-number/?owner=python-discord&name=bot-core
 
 ## Static Builds
 We deploy our docs to netlify to power static previews on PRs.
diff --git a/docs/_static/changelog.css b/docs/_static/changelog.css
new file mode 100644
index 00000000..343792a1
--- /dev/null
+++ b/docs/_static/changelog.css
@@ -0,0 +1,11 @@
+[data-theme='dark'] #changelog .dark,
+[data-theme='light'] #changelog .light,
+[data-theme='auto'] #changelog .light {
+    display: inline;
+}
+
+[data-theme='dark'] #changelog .light,
+[data-theme='light'] #changelog .dark,
+[data-theme='auto'] #changelog .dark {
+    display: none;
+}
diff --git a/docs/_static/changelog.js b/docs/_static/changelog.js
new file mode 100644
index 00000000..94834eaa
--- /dev/null
+++ b/docs/_static/changelog.js
@@ -0,0 +1,41 @@
+/** Update the changelog colors in dark mode */
+function changelog_color_main() {
+    const changelog = document.getElementById("changelog");
+
+    function updateEntryColor(span) {
+        const lightColorSpan = span;
+        const darkColorSpan = lightColorSpan.cloneNode(true);
+
+        lightColorSpan.parentElement.insertBefore(darkColorSpan, lightColorSpan);
+
+        lightColorSpan.classList.add("light");
+        darkColorSpan.classList.add("dark");
+
+        let color;
+        switch (darkColorSpan.textContent) {
+            case "Feature":
+                color = "#5BF38E";
+                break;
+            case "Support":
+                color = "#55A5E7";
+                break;
+            case "Bug":
+                color = "#E14F4F";
+                break;
+            default:
+                color = lightColorSpan.style.color;
+        }
+
+        darkColorSpan.style["color"] = color;
+    }
+
+    const TYPES = ["Feature", "Bug", "Support", "Breaking"];
+
+    if (changelog !== null) {
+        Array.from(changelog.getElementsByTagName("span"))
+            .filter(value => TYPES.includes(value.textContent))
+            .forEach(updateEntryColor)
+    }
+}
+
+changelog_color_main();
diff --git a/docs/changelog.rst b/docs/changelog.rst
new file mode 100644
index 00000000..3cee3a7a
--- /dev/null
+++ b/docs/changelog.rst
@@ -0,0 +1,124 @@
+.. See docs for details on formatting your entries
+   https://releases.readthedocs.io/en/latest/concepts.html
+
+Changelog
+=========
+
+- :support:`79` Restore on-site changelog.
+
+
+- :release:`7.1.0 <24th May 2022>`
+- :feature:`78` Bump Discord.py to :literal-url:`4cbe8f5 <https://github.com/Rapptz/discord.py/tree/4cbe8f58e16f6a76371ce45a69e0832130d6d24f>`:
+
+   - This fixes a bug with permission resolution when dealing with timed out members.
+
+
+- :release:`7.0.0 <10th May 2022>`
+- :bug:`75 major` Capture all characters up to a whitespace in the Discord Invite regex.
+- :breaking:`75` Discord invite regex no longer returns a URL safe result, refer to documentation for safely handling it.
+
+
+- :release:`6.4.0 <26th April 2022>`
+- :feature:`72` Bump discord.py to :literal-url:`5a06fa5 <https://github.com/Rapptz/discord.py/tree/5a06fa5f3e28d2b7191722e1a84c541560008aea>`:
+
+   - Notably, one of the commits in this bump dynamically extends the timeout of ``Guild.chunk()`` based on the number or members, so it should actually work on our guild now.
+
+
+- :release:`6.3.2 <25th April 2022>`
+- :bug:`69` Actually use ``statsd_url`` when it gets passed to ``BotBase``.
+
+
+- :release:`6.3.1 <21st April 2022>`
+- :bug:`68` Correct version number in pyproject.toml
+
+
+- :release:`6.3.0 <21st April 2022>`
+- :feature:`-` (Committed directly to main) Don't load modules starting with ``_``
+
+
+- :release:`6.2.0 <21st April 2022>`
+- :feature:`66` Load each cog in it's own task to avoid a single cog crashing entire load process.
+
+
+- :release:`6.1.0 <20th April 2022>`
+- :feature:`65` Add ``unqualify`` to the ``botcore.utils`` namespace for use in bots that manipulate extensions.
+
+
+- :release:`6.0.0 <19th April 2022>`
+- :breaking:`64` Bump discord.py to :literal-url:`987235d <https://github.com/Rapptz/discord.py/tree/987235d5649e7c2b1a927637bab6547244ecb2cf>`:
+
+   - This reverts a change to help command behaviour that broke our custom pagination
+   - This also adds basic forum channel support to discord.py
+
+
+- :release:`5.0.4 <18th April 2022>` 63
+
+   ..
+      Feature 63 Needs to be explicitly included below because it was improperly released within a bugfix version
+      instead of a minor release
+
+- :feature:`63` Allow passing an ``api_client`` to ``BotBase.__init__`` to specify the ``botcore.site_api.APIClient`` instance to use.
+
+
+- :release:`5.0.3 <18th April 2022>`
+- :bug:`61` Reconnect to redis session on setup if it is closed.
+
+
+- :release:`5.0.2 <5th April 2022>`
+- :bug:`56` Create a dummy ``AsyncstatsdClient`` before connecting to real url, in case a connection cannot be made on init.
+- :bug:`56` Move the creation of the ``asyncio.Event``, ``BotBase._guild_available`` to within the setup hook, to avoid a deprecation notice.
+
+
+- :release:`5.0.1 <2nd April 2022>`
+- :bug:`54` Move creation of BotBase's ``aiohttp.AsyncResolver`` to the async setup hook, to avoid deprecation notice
+
+
+- :release:`5.0.0 <2nd April 2022>`
+- :breaking:`42` Remove public extensions util.
+- :feature:`42` Add ``BotBase``, a ``discord.ext.commands.Bot`` sub-class, which abstracts a lot of logic shared between our bots.
+- :feature:`42` Add async statsd client.
+- :support:`42` Bump Discord.py to latest alpha commit.
+
+
+- :release:`4.0.0 <14th March 2022>`
+- :breaking:`39` Migrate back to Discord.py 2.0.
+
+
+- :release:`3.0.1 <5th March 2022>`
+- :bug:`37` Setup log tracing when ``botcore.utils.logging`` is imported so that it can be used within botcore functions.
+
+
+- :release:`3.0.0 <3rd March 2022>`
+- :breaking:`35` Move ``apply_monkey_patches()`` directly to `botcore.utils` namespace.
+
+
+- :release:`2.1.0 <24th February 2022>`
+- :feature:`34` Port the Site API wrapper from the bot repo.
+
+
+- :release:`2.0.0 <22nd February 2022>`
+- :breaking:`35` Moved regex to ``botcore.utils`` namespace
+- :breaking:`32` Migrate from discord.py 2.0a0 to disnake.
+- :feature:`32` Add common monkey patches.
+- :feature:`29` Port many common utilities from our bots:
+
+   - caching
+   - channel
+   - extensions
+   - loggers
+   - members
+   - scheduling
+- :support:`2` Added intersphinx to docs.
+
+
+- :release:`1.2.0 <9th January 2022>`
+- :feature:`12` Code block detection regex.
+
+
+- :release:`1.1.0 <2nd December 2021>`
+- :support:`2` Autogenerated docs.
+- :feature:`2` Regex utility.
+
+
+- :release:`1.0.0 <17th November 2021>`
+- :feature:`1` Core package, poetry, and linting CI.
diff --git a/docs/conf.py b/docs/conf.py
index 8459f3fb..1cea4026 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -7,6 +7,7 @@ import sys
 from pathlib import Path
 
 import git
+import releases
 import tomli
 from sphinx.application import Sphinx
 
@@ -46,6 +47,7 @@ extensions = [
     "sphinx.ext.todo",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
+    "releases",
     "sphinx.ext.linkcode",
     "sphinx.ext.githubpages",
 ]
@@ -82,10 +84,9 @@ html_short_title = project
 html_logo = "https://raw.githubusercontent.com/python-discord/branding/main/logos/logo_full/logo_full.min.svg"
 html_favicon = html_logo
 
-html_css_files = [
-    "index.css",
-    "logo.css",
-]
+static = Path("_static")
+html_css_files = utils.get_recursive_file_uris(static, "*.css")
+html_js_files = utils.get_recursive_file_uris(static, "*.js")
 
 utils.cleanup()
 
@@ -105,6 +106,12 @@ def skip(*args) -> bool:
 def setup(app: Sphinx) -> None:
     """Add extra hook-based autodoc configuration."""
     app.connect("autodoc-skip-member", skip)
+    app.add_role("literal-url", utils.emphasized_url)
+
+    # Add a `breaking` role to the changelog
+    releases.ISSUE_TYPES["breaking"] = "F50F10"  # This is the hex for a light red color
+    releases.reorder_release_entries = utils.reorder_release_entries
+    app.add_role("breaking", releases.issues_role)
 
 
 ignored_modules = [
@@ -148,3 +155,8 @@ intersphinx_mapping = {
 
 # -- Options for the linkcode extension --------------------------------------
 linkcode_resolve = functools.partial(utils.linkcode_resolve, SOURCE_FILE_LINK)
+
+
+# -- Options for releases extension ------------------------------------------
+releases_github_path = REPO_LINK.removeprefix("https://github.com/")
+releases_release_uri = f"{REPO_LINK}/releases/tag/v%s"
diff --git a/docs/index.rst b/docs/index.rst
index 98dcd611..0a375b90 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,8 +15,9 @@ Reference
 
 .. toctree::
    :caption: Other:
+   :hidden:
 
-   Changelog <https://github.com/python-discord/bot-core/blob/main/CHANGELOG.md>
+   changelog
 
 
 Extras
@@ -25,4 +26,4 @@ Extras
 * :ref:`genindex`
 * :ref:`search`
 * :repo-file:`Information <docs/README.md>`
-* :repo-file:`Changelog <CHANGELOG.md>`
+* :doc:`changelog`
diff --git a/docs/utils.py b/docs/utils.py
index 9116c130..aaa656c3 100644
--- a/docs/utils.py
+++ b/docs/utils.py
@@ -6,6 +6,10 @@ import inspect
 import typing
 from pathlib import Path
 
+import docutils.nodes
+import docutils.parsers.rst.states
+import releases
+
 PROJECT_ROOT = Path(__file__).parent.parent
 
 
@@ -108,7 +112,7 @@ def __get_included() -> set[str]:
         try:
             module = importlib.import_module(module_name)
         except ModuleNotFoundError:
-            return {}
+            return set()
         _modules = {module.__name__ + ".rst"}
 
         if hasattr(module, "__all__"):
@@ -118,3 +122,47 @@ def __get_included() -> set[str]:
         return _modules
 
     return get_all_from_module("botcore")
+
+
+def reorder_release_entries(release_list: list[releases.Release]) -> None:
+    """
+    Sort `releases` based on `release.type`.
+
+    This is meant to be used as an override for `releases.reorder_release_entries` to support
+    custom types.
+    """
+    order = {"breaking": 0, "feature": 1, "bug": 2, "support": 3}
+    for release in release_list:
+        release["entries"].sort(key=lambda entry: order[entry.type])
+
+
+def emphasized_url(
+    name: str, rawtext: str, text: str, lineno: int, inliner: docutils.parsers.rst.states.Inliner, *__
+) -> tuple[list, list]:
+    """
+    Sphinx role to add hyperlinked literals.
+
+    ReST: :literal-url:`Google <https://google.com>`
+    Markdown equivalent: [`Google`](https://google.com)
+
+    Refer to https://docutils.sourceforge.io/docs/howto/rst-roles.html for details on the input and output.
+    """
+    arguments = text.rsplit(maxsplit=1)
+    if len(arguments) != 2:
+        message = inliner.reporter.error(
+            f"`{name}` expects a message and a URL, formatted as: :{name}:`message <url>`",
+            line=lineno
+        )
+        problem = inliner.problematic(text, rawtext, message)
+        return [problem], [message]
+
+    message, url = arguments
+    url: str = url[1:-1]  # Remove the angled brackets off the start and end
+
+    literal = docutils.nodes.literal(rawtext, message)
+    return [docutils.nodes.reference(rawtext, "", literal, refuri=url)], []
+
+
+def get_recursive_file_uris(folder: Path, match_pattern: str) -> list[str]:
+    """Get the URI of any file relative to folder which matches the `match_pattern` regex."""
+    return [file.relative_to(folder).as_posix() for file in folder.rglob(match_pattern)]