Add pseudo auto-generated notes for the 2.x+ release branch (#339)

* an initial test

* For now manually generate

* re-gen file + some pre-commit fixes

* add releases.md to exclude list

* fix exclude

* Fix long title

* add releases.md to exclude for eol fixer

* Add extra instructions for releases - manual addition for now

* Add gh handles as links

* fix pre-commit

* Update environment.yml

* how about this?

* remove unused variable

* type the one function

* fix mypy

* Try fixing pre-commit

* this should match?

.pre-commit-config.yaml

@@ -10,8 +10,9 @@ repos:
     -   id: check-symlinks
     -   id: check-yaml
     -   id: end-of-file-fixer
+        exclude: ^(doc/source/releases.md)
     -   id: trailing-whitespace
-        exclude: ^.*\.(pdb|ambr)$
+        exclude: ^.*\.(pdb|ambr)|^(doc\/source\/releases.md)$
 -   repo: https://github.com/pycqa/isort
     rev: 5.12.0
     hooks:

doc/source/conf.py

@@ -84,6 +84,7 @@ def sort_authors(filename: str) -> list[str]:
     "sphinxcontrib.bibtex",
     "matplotlib.sphinxext.plot_directive",
     "mdanalysis_sphinx_theme",
+    "myst_parser",
 ]
 
 bibtex_bibfiles = ["references.bib"]

doc/source/index.rst

@@ -73,6 +73,7 @@ Wherever possible, do not take these conversations to private channels, includin
    examples/quickstart
    faq
    examples/README
+   releases
 
 .. toctree::
    :maxdepth: 1

doc/source/preparing_releases_and_hotfixes.rst

@@ -184,6 +184,13 @@ For now, the UserGuide is released at the same time as the core library. If it's
         cd doc/source/scripts
         python -m pytest tests/snapshot/ --snapshot-update
 
+#. Make a Pull Request with a re-generated ``releases.md`` which contains a copy of the GitHub release notes. This can be generated by doing:
+
+    .. code-block:: bash
+
+        cd doc/source/scripts
+        python gen_release_notes.py
+
 #. Create a new release tag and upload them for the UserGuide repository.
 
     .. code-block:: bash

doc/source/scripts/gen_release_notes.py

@@ -0,0 +1,47 @@
+import os
+import pathlib
+import re
+
+from github import Github
+
+
+def gen_release_notes(filename: str) -> None:
+    git = Github(os.environ["GITHUB_TOKEN"])
+    repo = git.get_repo("MDAnalysis/mdanalysis")
+
+    parent_directory = pathlib.Path(__file__).parent.parent
+    parent_directory.mkdir(exist_ok=True, parents=True)
+    filename = parent_directory / filename  # type: ignore
+
+    filetext = "# MDAnalysis Release Notes\n\n\n"
+
+    # Should be ordered
+    for release in repo.get_releases():
+        # MDAnalysis releases always follow a tag pattern of *-release_version
+        version = release.tag_name.split("-")[1]
+
+        # Only write out version 2.x+ since those are the only ones that
+        # we can guarantee similarly written notes for
+        if int(version.split(".")[0]) < 2:
+            continue
+
+        if release.body.startswith("###"):
+            filetext += release.body[1:]
+        else:
+            filetext += release.body
+
+        filetext += "\n\n"
+
+    # replace all @ starting handles with github links
+    # \b doesn't work so we're using \s and getting extra whitespace
+    handles = set(re.findall(r"\s@\w+", filetext))
+    for entry in handles:
+        new_word = f" [{entry[1:]}](https://github.com/{entry[2:]})"
+        filetext = filetext.replace(entry, new_word)
+
+    with open(filename, "w") as f:
+        f.write(filetext)
+
+
+if __name__ == "__main__":
+    gen_release_notes("releases.md")

environment.yml

@@ -22,6 +22,7 @@ dependencies:
   - ipython
   - ipywidgets<8.0.0
   - jupyter_contrib_nbextensions
+  - myst-parser
   - nbconvert # not called by any notebook explicitly but to download notebooks, or in nbsphinx
   - nbformat
   - nbsphinx
@@ -51,6 +52,8 @@ dependencies:
       - nbval
       # developer tooling
       - pre-commit
+      # doc generation dependency
+      - pygithub
       # mdanalysis and its tests and test data
       - git+https://github.com/MDAnalysis/mdanalysis@develop#egg=mdanalysis&subdirectory=package
       - git+https://github.com/MDAnalysis/mdanalysis@develop#egg=MDAnalysisTests&subdirectory=testsuite