feat: make release notes insert parts from markdown

[jcreedcmu]

Resolves #542.

Previously, we turned all headers into emphasized text regardless of level. With this change, we insert nested parts into the current verso document corresponding to the markdown structure.

[jcreedcmu]

This isn't right yet; it inserts consecutive parts more deeply nested than they ought to be, e.g. release note markdown

## foo
## bar
## baz

becomes rendered as if it was

## foo
### bar
#### baz

[jcreedcmu]

I think I see what I'm supposed to do instead from addPartsFromMarkdown's docstring...

[jcreedcmu]

This is now, I think, correct, unless we expect permalink icons to appear while hovering over section headers in the release notes. I tentatively expected that, and I observe that they do not appear.

I think traversal is still correctly assigning fresh ids to sections arising from markdown in the release notes, because the sections appear in the TOC sidebar, and clicking on them still correctly goes to the right url-with-fragment. I think this is where permalinks get created.

[jcreedcmu]

I'm interested in ignoring the prose checks for now as they are numerous and orthogonal to this change.

[david-christiansen]

If you stick class="no-vale" on the resulting HTML, the prose linter will ignore these.

[david-christiansen]

This is now, I think, correct, unless we expect permalink icons to appear while hovering over section headers in the release notes. I tentatively expected that, and I observe that they do not appear.

I think traversal is still correctly assigning fresh ids to sections arising from markdown in the release notes, because the sections appear in the TOC sidebar, and clicking on them still correctly goes to the right url-with-fragment. I think this is where permalinks get created.

To get a permalink, the section has to have a stable identifier. That represents our commitment to keeping it around and keeping that name. Because release notes are basically immutable, this is easy - some mangling of the title and version will suffice. You do this by assigning the tag field of each section's PartMetadata, which will also result in them appearing in the quickjump.

[jcreedcmu]

To get a permalink, the section has to have a stable identifier. That represents our commitment to keeping it around and keeping that name. Because release notes are basically immutable, this is easy - some mangling of the title and version will suffice. You do this by assigning the tag field of each section's PartMetadata, which will also result in them appearing in the quickjump.

Perfect, that's exactly the information I was interested in.

[jcreedcmu]

This PR now depends on leanprover/verso#539 to fix markdown header processing to be actually correct. @jrr6 's original implementation was good enough for the typical error explanations markdown, but had iiuc a slightly subtle bug for repeating headers at the same depth, which my PR aims to fix.

[jcreedcmu]

Is this (by exact decl_name%) tactic invocation appropriate here? As I understand it, I'm not able to literally write ``markdown because I want to refer to the very def markdown defined on line 32, right? So this is what I guessed would work instead, having seem decl_name% many places elsewhere. It does in fact seem to work, and using MessageData.hint below works to get argument deletion hints as well.

[jcreedcmu]

The one remaining thing holding me back from merging this PR as is is the failing vale prose check. It's unclear to me how I should best ensure class="no-vale" is applicable to the content of the release notes.

I could try wrapping individual blocks with the Block.noVale that the reference manual already defines, but it seems like this would require pretty invasive changes to addPartFromMarkdown on the verso side.

I'd love to add class="no-vale" to the <section> generated here... but the way it's currently called seems to be an obstacle to the idea of adding part metadata (perhaps containing, in general, a set of HTML tag attributes to add to <section>) because the metadata is already deleted by the time we reach the case the <section> is created.

Any other ideas?

I think this actually is a blocker because I believe, reading the workflow file for how vale is invoked, that it's not restricting its attention to changed files. So I conclude that if I break the reference-manual build with this change it's going to stay broken until fixed.

[jcreedcmu]

Discussion out of band led to the following conclusions:

• Vale checking is not state-aware: it's not trying to intelligently throw errors only on changed files. However, the build wasn't broken before this change, so probably the preprocessing that's already been applied was trying to exclude release notes, and something that I've changed disrupted that exclusion. I probably want to repair that disruption.
• In order to apply the "no-vale" class to all release note content, we would probably want to put it in the <section>. Doing that requires a bit of refactoring/generalizing how Verso handles parts and their metadata. It's likely feasible, but a bit more thinking, and I'm to get this PR out the door in a way that satisfies conservation of hackiness instead of pursuing that refactor.

[github-actions]

Preview for this PR is ready! 🎉 (also as a proofreading version). built with commit 1dfc0db.