Make changelog easy to parse (#6711)

.readthedocs.yml

@@ -7,6 +7,10 @@ build:
   jobs:
     install:
       - pip install .[doc]
+    post_build:
+      - mkdir -p docs/_build/doctrees docs/_build/markdown "$READTHEDOCS_OUTPUT/html/_markdown"
+      - python -m sphinx -T -b markdown -d docs/_build/doctrees -D "language=$READTHEDOCS_LANGUAGE" docs docs/_build/markdown
+      - cp docs/_build/markdown/changelog.md "$READTHEDOCS_OUTPUT/html/_markdown/changelog.md"
 
 sphinx:
   configuration: docs/conf.py

docs/_ext/changelog_contributors.py

@@ -0,0 +1,43 @@
+from typing import Any, Dict, List
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+
+
+class ChangelogContributors(SphinxDirective):
+    has_content = True
+
+    def run(self) -> List[nodes.Node]:
+        contributors = [contributor for line in self.content for contributor in line.split()]
+
+        comment_value = " ".join(contributors)
+        line_nodes = []
+        for contributor in contributors:
+            if line_nodes:
+                line_nodes.append(nodes.Text(", "))
+            line_nodes.append(
+                nodes.reference(
+                    contributor,
+                    f"@{contributor}",
+                    internal=False,
+                    refuri=f"https://github.com/sponsors/{contributor}",
+                )
+            )
+
+        node = nodes.line_block(
+            "",
+            nodes.comment("", f"RED-CHANGELOG-CONTRIBUTORS: {comment_value}"),
+            nodes.line("", "Thanks to all these amazing people who contributed to this release:"),
+            nodes.line("", "", *line_nodes),
+        )
+        return [node]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_directive("changelog-contributors", ChangelogContributors)
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/conf.py

@@ -44,7 +44,9 @@ extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.doctest",
     "sphinxcontrib_trio",
+    "sphinx_markdown_builder",
     "sphinx-prompt",
+    "changelog_contributors",
     "deprecated_removed",
     "prompt_builder",
 ]
@@ -230,6 +232,14 @@ linkcheck_ignore = [r"https://java.com*", r"https://chocolatey.org*"]
 linkcheck_retries = 3
 
 
+# -- Options for markdown builder ----------------------------------------
+
+markdown_http_base = os.environ.get(
+    "READTHEDOCS_CANONICAL_URL", "https://docs.discord.red/en/stable"
+)
+markdown_uri_doc_suffix = ".html"
+
+
 # -- Options for extensions -----------------------------------------------
 
 if dpy_version_info.releaselevel == "final":

requirements/extra-doc.in

@@ -1,6 +1,7 @@
 -c base.txt
 
 Sphinx
+sphinx-markdown-builder>=0.6.10
 sphinx-prompt
 sphinx_rtd_theme>1
 sphinxcontrib-trio

requirements/extra-doc.txt

@@ -34,6 +34,8 @@ sphinx==7.1.2
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
     #   sphinxcontrib-trio
+sphinx-markdown-builder==0.6.10
+    # via -r extra-doc.in
 sphinx-prompt==1.7.0
     # via -r extra-doc.in
 sphinx-rtd-theme==3.1.0
@@ -54,6 +56,8 @@ sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
 sphinxcontrib-trio==1.2.0
     # via -r extra-doc.in
+tabulate==0.9.0
+    # via sphinx-markdown-builder
 urllib3==2.2.3
     # via requests
 zipp==3.20.2

tools/release_helper.py

@@ -965,12 +965,7 @@ def cli_contributors(version: str, *, show_not_merged: bool = False) -> None:
 
 
 def get_contributors(version: str, *, show_not_merged: bool = False) -> None:
-    print(
-        ", ".join(
-            f":ghuser:`{username}`"
-            for username in _get_contributors(version, show_not_merged=show_not_merged)
-        )
-    )
+    print(*_get_contributors(version, show_not_merged=show_not_merged))
 
 
 def _get_contributors(version: str, *, show_not_merged: bool = False) -> List[str]:

tox.ini

@@ -59,6 +59,7 @@ extras = doc
 commands =
     sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out/html" -W --keep-going -bhtml
     sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out/doctest" -W --keep-going -bdoctest
+    sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out/markdown" docs/changelog.rst -W --keep-going -bmarkdown
 
 [testenv:style]
 description = Stylecheck the code with black to see if anything needs changes.