DOC: Clarify the difference between document and section references#26405
DOC: Clarify the difference between document and section references#26405story645 merged 1 commit intomatplotlib:mainfrom
Conversation
| 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.
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
58a35aa to
2c2a7b9
Compare
story645
left a comment
There was a problem hiding this comment.
Can self merge or sort out parenthesis and then self merge.
| |ref-dir|_ reference label (associated link to an anchor associated with a heading | ||
| with a section) |
There was a problem hiding this comment.
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.
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.
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.
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-doc Backport PR #26405 on branch v3.7.2-doc (DOC: Clarify the difference between document and section references)
…405-on-v3.7.x Backport PR #26405 on branch v3.7.x (DOC: Clarify the difference between document and section references)
…ument and section references
…t-of-pr-26405-on-v3.7.x Backport PR matplotlib#26405 on branch v3.7.x (DOC: Clarify the difference between document and section references)
…ument and section references
…t-of-pr-26405-on-v3.7.2-doc Backport PR matplotlib#26405 on branch v3.7.2-doc (DOC: Clarify the difference between document and section references)
No description provided.