Add direct anchors to regex syntax documentation

[bmispelon]

BPO	38975
Nosy	@terryjreedy, @serhiy-storchaka, @bmispelon, @JulienPalard
PRs	gh-83156: Add dedicated anchor for regexp syntax elements #17470

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-12-04.21:12:31.099>
labels = ['type-feature', 'docs']
title = 'Add direct anchors to regex syntax documentation'
updated_at = <Date 2019-12-09.21:41:44.691>
user = 'https://github.com/bmispelon'

bugs.python.org fields:

activity = <Date 2019-12-09.21:41:44.691>
actor = 'bmispelon'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-12-04.21:12:31.099>
creator = 'bmispelon'
dependencies = []
files = []
hgrepos = []
issue_num = 38975
keywords = ['patch']
message_count = 3.0
messages = ['357831', '357951', '358145']
nosy_count = 5.0
nosy_names = ['terry.reedy', 'docs@python', 'serhiy.storchaka', 'bmispelon', 'mdk']
pr_nums = ['17470']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue38975'
versions = []

[bmispelon]

While writing documentation about regexps for a project I help maintain, I wanted to link to some specific aspects of Python's implementation (in my case, non-capturing groups) which are described on https://docs.python.org/3/library/re.html.

There are no visible ¶ anchors for the items in the "Regular Expression Syntax" section. Inspecting the generated HTML, there does seem to be auto-generated ids (like #index-16 for example) but I wouldn't like to rely on those as I'm not sure how stable they are.

I couldn't find how to add the ¶ symbol show up next to the titles but I have a PR that adds a bunch of references so that items can be linked directly.

[terryjreedy]

¶ anchors are generated automatically for headers, but I don't know what the policy might be for items within section. It might be useful to add some subsection headers within the Regular Expression Syntax section.

[bmispelon]

I've tried using subsection (level 3) for each syntax element and I'm not sure it's a big improvement.

Pros:

• Visible ¶ anchors which make it easier to copy/paste a reference link

Cons:

• <h3> headings have a slightly different style (bigger font, no background color)
• All the added titles show up in the table of content (might not be a problem)
• Lots of re-indenting is needed which makes the diff quite noisy (even without reflowing the paragraphs)

I'm not sure what's the best way to share this alternative. A new PR? An extra commit on the existing PR?