MAINT: ensure towncrier can be run >1x, and is included in spin docs

This allows accumulating snippets into the main release notes file and
committing the result during a release cycle. It will also make Sphinx
formatting errors, cross-link issues, etc. visible when docs get built
locally. This will allow fixing them as we go, rather than leaving it
broken in devdocs and then having to fix it in one go once `towncrier`
is run once right before or after creating a release branch.

xref numpygh-25921 and numpygh-25827 for recent issues with this.

[skip azp] [skip actions] [skip cirrus]

Author: rgommers

.gitignore

@@ -120,6 +120,7 @@ Thumbs.db
 #############################
 doc/source/savefig/
 doc/source/**/generated/
+doc/source/release/notes-towncrier.rst
 
 # Things specific to this project #
 ###################################

.spin/cmds.py

@@ -162,6 +162,15 @@ def docs(ctx, sphinx_target, clean, first_build, jobs):
 
     """
     meson.docs.ignore_unknown_options = True
+
+    # Run towncrier without staging anything for commit. This is the way to get
+    # release notes snippets included in a local doc build.
+    cmd = ['towncrier', 'build', '--version', '2.x.y', '--keep', '--draft']
+    p = subprocess.run(cmd, check=True, capture_output=True, text=True)
+    outfile = curdir.parent / 'doc' / 'source' / 'release' / 'notes-towncrier.rst'
+    with open(outfile, 'w') as f:
+        f.write(p.stdout)
+
     ctx.forward(meson.docs)
 
 

doc/RELEASE_WALKTHROUGH.rst

@@ -94,10 +94,12 @@ needed information.
 Finish the release notes
 ------------------------
 
-If this is the first release in a series the release note is generated, see
-the release note in ``doc/release/upcoming_changes/README.rst`` to see how to
-do this. Generating the release notes will also delete all the news
-fragment files in ``doc/release/upcoming_changes/``.
+If there are any release notes snippets in ``doc/release/upcoming_changes/``,
+run ``spin docs`` to build the docs, incorporate the contents of the generated
+``doc/source/release/notes-towncrier.rst`` file into the release notes file
+(e.g., ``doc/source/release/2.3.4-notes.rst``), and delete the now-processed
+snippets in ``doc/release/upcoming_changes/``. This is safe to do multiple
+times during a release cycle.
 
 The generated release note will always need some fixups, the introduction will
 need to be written, and significant changes should be called out. For patch

doc/release/upcoming_changes/README.rst

@@ -50,9 +50,10 @@ and double-backticks for code.
 If you are unsure what pull request type to use, don't hesitate to ask in your
 PR.
 
-You can install ``towncrier`` and run ``towncrier build --draft --version 1.18``
-if you want to get a preview of how your change will look in the final release
-notes.
+``towncrier`` is required to build the docs; it will be automatically run when
+you build the docs locally with ``spin docs``. You can also run ``towncrier
+build --draft --version 1.18`` if you want to get a preview of how your change
+will look in the final release notes.
 
 .. note::
 

doc/release/upcoming_changes/template.rst

@@ -1,8 +1,3 @@
-{% set title = "NumPy {} Release Notes".format(versiondata.version) %}
-{{ "=" * title|length }}
-{{ title }}
-{{ "=" * title|length }}
-
 {% for section, _ in sections.items() %}
 {% set underline = underlines[0] %}{% if section %}{{ section }}
 {{ underline * section|length }}{% set underline = underlines[1] %}
@@ -32,8 +27,7 @@ No significant changes.
 {% endif %}
 {% endfor %}
 {% else %}
-No significant changes.
-
+(no release note snippets found)
 
 {% endif %}
 {% endfor %}

doc/source/release/2.0.0-notes.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: numpy
+
 =========================
 NumPy 2.0.0 Release Notes
 =========================
@@ -1304,3 +1306,9 @@ You can use ``np.logical_or.reduce`` and ``np.logical_and.reduce``
 to achieve the previous behavior.
 
 (`gh-25712 <https://github.com/numpy/numpy/pull/25712>`__)
+
+
+
+**Content from release note snippets in doc/release/upcoming_changes:**
+
+.. include:: notes-towncrier.rst

doc/source/release/template.rst

@@ -1,45 +1,21 @@
 :orphan:
 
+.. currentmodule:: numpy
+
 ==========================
-NumPy 1.xx.x Release Notes
+NumPy 2.xx.x Release Notes
 ==========================
 
 
 Highlights
 ==========
 
-
-New functions
-=============
-
-
-Deprecations
-============
-
-
-Future Changes
-==============
-
-
-Expired deprecations
-====================
-
-
-Compatibility notes
-===================
-
-
-C API changes
-=============
-
-
-New Features
-============
+*We'll choose highlights for this release near the end of the release cycle.*
 
 
-Improvements
-============
+.. if release snippets have been incorporated already, uncomment the follow
+   line (leave the `.. include:: directive)
 
+.. **Content from release note snippets in doc/release/upcoming_changes:**
 
-Changes
-=======
+.. include:: notes-towncrier.rst

pyproject.toml

@@ -60,10 +60,8 @@ tracker = "https://github.com/numpy/numpy/issues"
 "release notes" = "https://numpy.org/doc/stable/release"
 
 [tool.towncrier]
-    # Do no set this since it is hard to import numpy inside the source directory
-    # the name is hardcoded. Use "--version 1.18.0" to set the version
     single_file = false
-    filename = "doc/source/release/{version}-notes.rst"
+    filename = "doc/source/release/notes-towncrier.rst"
     directory = "doc/release/upcoming_changes/"
     issue_format = "`gh-{issue} <https://github.com/numpy/numpy/pull/{issue}>`__"
     template = "doc/release/upcoming_changes/template.rst"