In line 225, this is called a section reference name and the way we name this thing should be consistent.

I vote for reference label since that's what sphinx calls em in their docs https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-arbitrary-locations

Done.

I'm generally not a fan of these long parenthesis - what are we trying to get at here?

Usually, I'm not a fan of parantheses here as well.

Motivation: The technical reference point is the label, but semantically we refer to the associated section. I wanted to

• have the focus on the label, because that's what you have to specify in the role
• also give the context that the label represents a section

The parantheses should lower the importance of the context information wrt to the label itself.

I think that info comes across in the where does it link information? And that we have an example underneath?

You are right. I've removed the parenthesis including its content.