Conversation
FYI: opus 5.5 is out, and in my experience quite a bit better :) |
|
Nice PR number, BTW ( |
|
Thanks, @jorenham, I've had a look at the new model, and you are right. I will review these changes with 5.5 and update the commits. |
b99227f to
635d64f
Compare
|
Actually, this is quite nice: we no longer have to use pandoc to convert snippets! Thought @ngoldbaum would appreciate that part. |
| @@ -0,0 +1 @@ | |||
|
|
|||
There was a problem hiding this comment.
That file is empty on main too 🤷
There was a problem hiding this comment.
I probably forgot to git rm it and no one noticed.
Switch the towncrier template, output file and release note skeleton to
Markdown, and enable myst_parser in the Sphinx build.
Single backticks are literal text in Markdown, so cross-references now need
an explicit role such as {func}`numpy.sum`. Unlike previously, a role with
a target that does not exist now fails the CI doc build. A
missing-reference handler resolves the `np.` alias, so {func}`np.sum` also
links.
Exclude notes-towncrier.md from the Sphinx sources: it is pulled in through
an {include} from the release notes themselves.
tools/write_release.py converts the notes to GitHub Markdown, so pandoc is
no longer required to convert rst to md. The GitHub release no longer
attaches the notes as a file, since those appear in the release
description.
Assisted-by: claude-code:claude-opus-5-5
Headings now are `###`, literals use single backticks, cross-references get a role that depends on the type of object it refers to (module, function, etc.). Assisted-by: claude-code:claude-opus-5
635d64f to
b845fff
Compare
| @@ -0,0 +1,7 @@ | |||
| ### {func}`numpy.common_type` now raises a clear error for non-array input | |||
|
|
|||
| Passing a dtype or scalar type to {func}`numpy.common_type`, such as | |||
There was a problem hiding this comment.
This is what I was talking about with new syntax. Even if it is annoying for people used to markdown, it’s really nice that single backticks in rst handle this automatically
There was a problem hiding this comment.
Would you prefer a generic role, such as
{np}``common_type``
?
Func, mod, class feel like easy to remember distinctions, but we can make tweaks like this as long as it remains myst markdown.
There was a problem hiding this comment.
I don’t think that’s much better 🤷♂️
Anyway it’s a tradeoff and it’s not a huge deal to me personally if we do change it.
There was a problem hiding this comment.
I like it; it's like type annotations 🥳
There was a problem hiding this comment.
really nice that single backticks in rst handle this automatically
I always have to remove all the links and turn them into code because they cannot be resolved in the posted notes. I would be happier if they were never used in the snippets.
There was a problem hiding this comment.
I would be happier if they were never used in the snippets.
That's too bad. I wonder if there's a better way to make sure the nice links show up in the github release notes.
There was a problem hiding this comment.
I imagine we can turn them into absolute docs links. Versioning won't be straightforward, though, but if we made a compromise like "always point to the dev docs for that function" it'd be easier.
|
I am thinking of changing the changelogs to markdown as well. They are not part of the published documentation, so that makes translation almost trivial. |
This branch has not been deployed
4 participants
This is a proof-of-concept PR to show how markdown release notes would look using the
myst_parserplugin for Sphinx. There are two commits, which I recommend we look at separately: the first is for updating the Sphinx machinery (that one we can cherry-pick in the future), and the second to show the syntax changes to the release note snippets themselves (we wouldn't merge this, since we can simply switch to the new machinery after a next release).myst_parseris pretty forgiving, in the sense that if a role is not used bymyst, it passes it through as a Sphinx directive. That's why so few changes are needed to the notes, and why maintainers won't need to memorize a new syntax. If, in some future, we switch over to https://mystmd.org, the changes will be more extensive, since that engine only supports myst markdown.I made this PR after a discussion on the community call, to better inform a decision; it is simply a demonstration, and there is no NEED to switch now.
See #23805 for background.
AI Disclosure
The changes were generated using claude-code:claude-opus-5.
The PR description is written by me.