[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.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[hugovk]

It's been a while!

OK, let's do this:

• Apply :tocdepth: 3 at the top of the file
• Add a h3 "Special characters" just above "The special characters are:"
• Add a h3 "Special sequences" just above "The special sequences consist of..."
• Demote term headings (like .) to h4

This way the terms can be linked, we get pilcrow hovers, and the sidebar isn't too busy.

@bmispelon Would you like to bring this up-to-date and do this? Or shall I?

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35366895 | 📁 Comparing b9d9e8b against main (2507a7f)

  🔍 Preview build  

2 files changed

± library/re.html
± whatsnew/changelog.html

[miss-islington-app]

Thanks @bmispelon for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @bmispelon for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @bmispelon and @ambv, I could not cleanly backport this to 3.14 due to a conflict.

Please backport manually with cherry_picker, see the devguide for more information.

cherry_picker 321925c92c9e67864cafa1566840927f6f07e90a 3.14

[miss-islington-app]

Sorry, @bmispelon and @ambv, I could not cleanly backport this to 3.15 due to a conflict.

Please backport manually with cherry_picker, see the devguide for more information.

cherry_picker 321925c92c9e67864cafa1566840927f6f07e90a 3.15

[bedevere-app]

GH-160606 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

GH-160607 is a backport of this pull request to the 3.14 branch.