Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork7.9k
DOC: Clarify the difference between document and section references#26405
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
doc/devel/document.rst Outdated
| Directive Links target Representation in rendered HTML | ||
| ========= =========================== =========================================== | ||
| ``:doc:`` document link to a page | ||
| ``:ref:`` ReST label (associated with link to an anchor associated with a heading |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
In line 225, this is called a section reference name and the way we name this thing should be consistent.
I vote forreference label since that's what sphinx calls em in their docshttps://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-arbitrary-locations
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Done.
58a35aa to2c2a7b9CompareThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Can self merge or sort out parenthesis and then self merge.
doc/devel/document.rst Outdated
| |ref-dir|_ reference label (associated link to an anchor associated with a heading | ||
| with a section) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I'm generally not a fan of these long parenthesis - what are we trying to get at here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I think that info comes across in the where does it link information? And that we have an example underneath?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
You are right. I've removed the parenthesis including its content.
Co-authored-by: hannah <story645@gmail.com>
…ument and section references
…ument and section references
…405-on-v3.7.2-docBackport PR#26405 on branch v3.7.2-doc (DOC: Clarify the difference between document and section references)
…405-on-v3.7.xBackport PR#26405 on branch v3.7.x (DOC: Clarify the difference between document and section references)
No description provided.