tools: Add update_changelog.py helper to tools directory

This new helper script takes a branch name as input, then fetches
`CHANGELOG.md` from that branch in the upstream mixxxdj/mixxx repo,
converts the changelog into sphinx's ReStructured Text format and writes
it to `source/chapters/appendix/version_history.py`.

This makes keeping the manual repository changelog in sync with the code
repository changelog much easier and will allow automation in the
future.

requirements.txt

@@ -1,7 +1,9 @@
 sphinx
 sphinx-intl
 graphviz
+m2r2
 markupsafe
+requests
 transifex-client
 sphinxcontrib-svg2pdfconverter
 sphinx-rtd-theme==0.5.2

tools/update_changelog.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+import argparse
+import os
+import re
+
+import m2r2
+import requests
+
+
+TEMPLATE = """
+.. This is a generated file. Do not edit it manually, because it is updated
+   automatically via tools/update_changelog.py.
+
+.. include:: /shortcuts.rstext
+
+.. _appendix-version-history:
+
+{content}
+
+.. seealso:: For an overview of previous versions, `take a look
+             <https://launchpad.net/mixxx/+series>`_ at the timeline.
+"""
+
+
+def fetch_changelog(branch):
+    r = requests.get(
+        "https://raw.githubusercontent.com/mixxxdj/mixxx/"
+        f"{branch}/CHANGELOG.md"
+    )
+    r.raise_for_status()
+    return r.text
+
+
+def changelog_to_rst(changelog):
+    # Replace headline with "Version History"
+    changelog = re.sub(
+        "^# Changelog$",
+        "# Version History",
+        changelog,
+        flags=re.MULTILINE | re.IGNORECASE,
+    )
+
+    # Ensure that all launchpad issues are hyperlinks
+    changelog = re.sub(
+        r"(?!\[)\blp:?(?P<lpid>\d+)\b(?!\])",
+        r"[lp:\g<lpid>](https://bugs.launchpad.net/mixxx/+bug/\g<lpid>)",
+        changelog,
+    )
+
+    # Ensure that all GitHub PRs are hyperlinks
+    changelog = re.sub(
+        r"(?!\[)#\b(?P<ghid>\d+)\b(?!\])",
+        r"[#\g<ghid>](https://github.com/mixxxdj/mixxx/pull/\g<ghid>)",
+        changelog,
+    )
+
+    return TEMPLATE.lstrip().format(content=m2r2.convert(changelog))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-b", "--branch", required=True)
+    args = parser.parse_args(argv)
+
+    changelog = fetch_changelog(args.branch)
+    changelog = changelog_to_rst(changelog)
+
+    path = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)),
+        "../source/chapters/appendix/version_history.rst",
+    )
+    with open(path, mode="w") as fp:
+        fp.write(changelog)
+
+
+if __name__ == "__main__":
+    main()