8000 Merge pull request #25933 from rgommers/fix-towncrier-invocation · numpy/numpy@8b0bc6d · GitHub
[go: up one dir, main page]
Skip to content

Commit 8b0bc6d

Browse files
charrischarris
authored
Merge pull request #25933 from rgommers/fix-towncrier-invocation
MAINT: ensure towncrier can be run >1x, and is included in `spin docs`
2 parents 2c95083 + e1fcb0f commit 8b0bc6d

File tree

8 files changed

+39
-52
lines changed

8 files changed

+39
-52
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ Thumbs.db
120120
#############################
121121
doc/source/savefig/
122122
doc/source/**/generated/
123+
doc/source/release/notes-towncrier.rst
123124

124125
# Things specific to this project #
125126
###################################

‎.spin/cmds.py

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,15 @@ def docs(ctx, sphinx_target, clean, first_build, jobs):
162162
163163
"""
164164
meson.docs.ignore_unknown_options = True
165+
166+
# Run towncrier without staging anything for commit. This is the way to get
167+
# release notes snippets included in a local doc build.
168+
cmd = ['towncrier', 'build', '--version', '2.x.y', '--keep', '--draft']
169+
p = subprocess.run(cmd, check=True, capture_output=True, text=True)
170+
outfile = curdir.parent / 'doc' / 'source' / 'release' / 'notes-towncrier.rst'
171+
with open(outfile, 'w') as f:
172+
f.write(p.stdout)
173+
165174
ctx.forward(meson.docs)
166175

167176

‎doc/RELEASE_WALKTHROUGH.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -94,18 +94,18 @@ needed information.
9494
Finish the release notes
9595
------------------------
9696

97-
If this is the first release in a series the release note is generated, see
98-
the release note in ``doc/release/upcoming_changes/README.rst`` to see how to
99-
do this. Generating the release notes will also delete all the news
100-
fragment files in ``doc/release/upcoming_changes/``.
97+
If there are any release notes snippets in ``doc/release/upcoming_changes/``,
98+
run ``spin docs`` to build the docs, incorporate the contents of the generated
99+
``doc/source/release/notes-towncrier.rst`` file into the release notes file
100+
(e.g., ``doc/source/release/2.3.4-notes.rst``), and delete the now-processed
101+
snippets in ``doc/release/upcoming_changes/``. This is safe to do multiple
102+
times during a release cycle.
101103

102104
The generated release note will always need some fixups, the introduction will
103105
need to be written, and significant changes should be called out. For patch
104106
releases the changelog text may also be appended, but not for the initial
105107
release as it is too long. Check previous release notes to see how this is
106-
done. Note that the ``:orphan:`` markup at the top, if present, will need
107-
changing to ``.. currentmodule:: numpy`` and the ``doc/source/release.rst``
108-
index file will need updating.
108+
done.
109109

110110

111111
Set the release version

‎doc/release/upcoming_changes/README.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,10 @@ and double-backticks for code.
5050
If you are unsure what pull request type to use, don't hesitate to ask in your
5151
PR.
5252

53-
You can install ``towncrier`` and run ``towncrier build --draft --version 1.18``
54-
if you want to get a preview of how your change will look in the final release
55-
notes.
53+
``towncrier`` is required to build the docs; it will be automatically run when
54+
you build the docs locally with ``spin docs``. You can also run ``towncrier
55+
build --draft --version 1.18`` if you want to get a preview of how your change
56+
will look in the final release notes.
5657

5758
.. note::
5859

‎doc/release/upcoming_changes/template.rst

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,3 @@
1-
{% set title = "NumPy {} Release Notes".format(versiondata.version) %}
2-
{{ "=" * title|length }}
3-
{{ title }}
4-
{{ "=" * title|length }}
5-
61
{% for section, _ in sections.items() %}
72
{% set underline = underlines[0] %}{% if section %}{{ section }}
83
{{ underline * section|length }}{% set underline = underlines[1] %}
@@ -32,8 +27,7 @@ No significant changes.
3227
{% endif %}
3328
{% endfor %}
3429
{% else %}
35-
No significant changes.
36-
30+
(no release note snippets found)
3731

3832
{% endif %}
3933
{% endfor %}

‎doc/source/release/2.0.0-notes.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. currentmodule:: numpy
2+
13
=========================
24
NumPy 2.0.0 Release Notes
35
=========================
@@ -1321,3 +1323,9 @@ You can use ``np.logical_or.reduce`` and ``np.logical_and.reduce``
13211323
to achieve the previous behavior.
13221324

13231325
(`gh-25712 <https://github.com/numpy/numpy/pull/25712>`__)
1326+
1327+
1328+
1329+
**Content from release note snippets in doc/release/upcoming_changes:**
1330+
1331+
.. include:: notes-towncrier.rst

‎doc/source/release/template.rst

Lines changed: 8 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,21 @@
11
:orphan:
22

3+
.. currentmodule:: numpy
4+
35
==========================
4-
NumPy 1.xx.x Release Notes
6+
NumPy 2.xx.x Release Notes
57
==========================
68

79

810
Highlights
911
==========
1012

11-
12-
New functions
13-
=============
14-
15-
16-
Deprecations
17-
============
18-
19-
20-
Future Changes
21-
==============
22-
23-
24-
Expired deprecations
25-
====================
26-
27-
28-
Compatibility notes
29-
===================
30-
31-
32-
C API changes
33-
=============
34-
35-
36-
New Features
37-
============
13+
*We'll choose highlights for this release near the end of the release cycle.*
3814

3915

40-
Improvements
41-
============
16+
.. if release snippets have been incorporated already, uncomment the follow
17+
line (leave the `.. include:: directive)
4218
19+
.. **Content from release note snippets in doc/release/upcoming_changes:**
4320
44-
Changes
45-
=======
21+
.. include:: notes-towncrier.rst

‎pyproject.toml

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,8 @@ tracker = "https://github.com/numpy/numpy/issues"
6060
"release notes" = "https://numpy.org/doc/stable/release"
6161

6262
[tool.towncrier]
63-
# Do no set this since it is hard to import numpy inside the source directory
64-
# the name is hardcoded. Use "--version 1.18.0" to set the version
6563
single_file = false
66-
filename = "doc/source/release/{version}-notes.rst"
64+
filename = "doc/source/release/notes-towncrier.rst"
6765
directory = "doc/release/upcoming_changes/"
6866
issue_format = "`gh-{issue} <https://github.com/numpy/numpy/pull/{issue}>`__"
6967
template = "doc/release/upcoming_changes/template.rst"

0 commit comments

Comments
 (0)
0