Automatically add new branch 'What's New' to toctree

Author: hugovk

run_release.py

@@ -1169,12 +1169,34 @@ def maybe_prepare_new_main_branch(db: ReleaseShelf) -> None:
         cwd=db["git_repo"],
     )
 
+    whatsnew_toctree_file = "Doc/whatsnew/index.rst"
+    with cd(db["git_repo"]):
+        update_whatsnew_toctree(db, whatsnew_toctree_file)
+
+    subprocess.check_call(
+        ["git", "add", whatsnew_toctree_file],
+        cwd=db["git_repo"],
+    )
+
     subprocess.check_call(
         ["git", "commit", "-a", "-m", f"Python {new_release}"],
         cwd=db["git_repo"],
     )
 
 
+def update_whatsnew_toctree(db: ReleaseShelf, filename: str) -> None:
+    release_tag: release_mod.Tag = db["release"]
+    this_rst = f"   {release_tag.major}.{release_tag.minor}.rst"
+    next_rst = f"   {release_tag.major}.{release_tag.minor+1}.rst"
+    new = next_rst + "\n" + this_rst
+
+    with open(filename) as f:
+        contents = f.read()
+    contents = contents.replace(this_rst, new)
+    with open(filename, "w") as f:
+        f.write(contents)
+
+
 def branch_new_versions(db: ReleaseShelf) -> None:
     release_tag: release_mod.Tag = db["release"]
 

tests/test_run_release.py

@@ -208,3 +208,20 @@ def test_modify_the_docs_by_version_page_final_yes(capsys, monkeypatch) -> None:
         "* `Python 3.13.3 <https://docs.python.org/release/3.13.3/>`_, documentation released on"
         in capsys.readouterr().out
     )
+
+
+def test_update_whatsnew_toctree(tmp_path: Path) -> None:
+    # Arrange
+    # Only first beta triggers update
+    db = {"release": Tag("3.14.0b1")}
+
+    original_toctree_file = Path(__file__).parent / "whatsnew_index.rst"
+    toctree__file = tmp_path / "patchlevel.h"
+    toctree__file.write_text(original_toctree_file.read_text())
+
+    # Act
+    run_release.update_whatsnew_toctree(cast(ReleaseShelf, db), str(toctree__file))
+
+    # Assert
+    new_contents = toctree__file.read_text()
+    assert "   3.15.rst\n   3.14.rst\n" in new_contents

tests/whatsnew_index.rst

@@ -0,0 +1,46 @@
+.. _whatsnew-index:
+
+######################
+ What's New in Python
+######################
+
+The "What's New in Python" series of essays takes tours through the most
+important changes between major Python versions.  They are a "must read" for
+anyone wishing to stay up-to-date after a new release.
+
+.. toctree::
+   :maxdepth: 2
+
+   3.14.rst
+   3.13.rst
+   3.12.rst
+   3.11.rst
+   3.10.rst
+   3.9.rst
+   3.8.rst
+   3.7.rst
+   3.6.rst
+   3.5.rst
+   3.4.rst
+   3.3.rst
+   3.2.rst
+   3.1.rst
+   3.0.rst
+   2.7.rst
+   2.6.rst
+   2.5.rst
+   2.4.rst
+   2.3.rst
+   2.2.rst
+   2.1.rst
+   2.0.rst
+
+The "Changelog" is an HTML version of the :pypi:`file built<blurb>`
+from the contents of the
+:source:`Misc/NEWS.d` directory tree, which contains *all* nontrivial changes
+to Python for the current version.
+
+.. toctree::
+   :maxdepth: 2
+
+   changelog.rst