gh-83156: Add dedicated anchor for regexp syntax elements

[bmispelon]

• Issue: Add direct anchors to regex syntax documentation #83156

[hugovk]

I rebased this and build the docs:

cd Doc
make clean venv html

And it does add anchors like syntax-dollar which you can visit by going to re.html#syntax-dollar:

But there's no ¶ hyperlink to click on and it's not obvious unless you know they exist or inspect the source. Should they be made more obvious?

[JelleZijlstra]

Thanks for your PR, and sorry it has been open for so long!

I think these anchors are useful, but agree with @hugovk that it's hard to discover them with no ¶ available to click on. Is it possible to add that?

[bmispelon]

Is it possible to add that?

Thanks for getting back to the PR eventually. I will look into how to add the pillcrow ¶ to the links.

[bmispelon]

I added a new commit that turns all the headings into <h3> which automatically gives them a nice ¶ on hover.

It does change the look of the page a little bit but I don't think it's for the worse personally. Here's the before/after on my machine:

Before:

After:

I also took the opportunity to add an ..index reference to the new (?>...) syntax which seemed to be missing, I hope that's ok.

[hugovk]

Also a long list in the menu on the left.

Before:

After:

[CAM-Gerlach]

Adding :name: s to the index directives will generate a stable cross-reference target label that can be referenced internally or via Intersphinx with the :ref: role, as well as externally by copying the URL in the index, or manually grabbing the id of the anchor span inspecting the HTML. This means that anyone referencing this in Sphinx documentation, or with a bit of HTML-fu, can reference each term, and they will also be searchable with Sphinx 5.2.0+ due to sphinx-doc/sphinx#10819 .

However, if we do want easily-clickable and copyable external links with the fragment id in the rendered document, section headings would need to be added. I'm not sure a way around them also being in the ToC without hacks or pushing them down 2+ heading levels, but maybe @AA-Turner knows a way? This hopefully won't be an issue in the future, though, as if we adopt a Sphinx theme like Lutra that separates the inter- and intra-document ToC into left and right sidebars, and for which we can limit the ToC depth of the latter to 2, we could avoid displaying them by only adding one layer of higher level sections (which seems quite appropriate to the current document content) and limiting page ToCs to displaying only up to h3 heading levels.