Open timhoffm opened 6 days ago
This issue takes some deep thinking and comprehensively writing the doc won't be easy.
Unordered thoughts that may need consideration:
We have to groups of references:
ReferenceRole
: CVE
, CWE
, PEP
, RFC
, Manpage
, IndexRole
XRefRole
: AnyXRefRole
, CXRefRole
, CPPXRefRole
, JSXRefRole
, PyXRefRole
, EnvVarXRefRole
, OptionXRefRole
, MathReferenceRole
t.b.d.: Are the two categories merely implementation details or should they be documented as two kinds of references, i.e. should we group / point out the differences in the docs?What are the common aspects of all references? I believe at least the points "Custom link text" and "Suppressed link" from https://www.sphinx-doc.org/en/master/usage/referencing.html
"Cross-referencing syntax" is a sub-page of "Roles"; and cross-references are a substantial part of all roles. Do we want to keep the hierarchy or do we want to flatten it? Related: If "Cross-referencing syntax" is valuable as its own page, should we mention cross-referencing roles on both pages? - Likely yes, but one of them should only have a short mention and link to the detailed description in the other one.
The following roles are essentially cross-links but are only mentioned in "Roles":
:manpage:
,:pep:
,:rfc:
,:cve:
,:cwe:
This initial proposal makes 100% sense and clarifies a long-standing source of confusion. I've stared at the said pages and known of the mix-up for years. Having to open&skim through both pages every time I need a refresher has been frustrating.
Good call!
The heading Cross-referencing syntax in the roles doc should possibly have 2 sub-headings. Phrasing and layout of this section are key, here's a possible draft to give an idea:
Roles for cross-referencing
Cross-references in general See Cross-referencing syntax.
Cross-reference roles that aren't domain specific are:
Keep the link list for reference and add the roles being moved.
Are the two categories merely implementation details or should they be documented as two kinds of references
I think it's overbearing for readers (and especially beginners) to expose them to these internals. The document layout should be enough to intuitively establish the difference.
(...) cross-references are a substantial part of all roles
The other way around: not all roles have a part in cross-referencing, but all cross-references are roles.
"Cross-referencing syntax" is a sub-page of "Roles"
In strict Sphinx terms both are separate .rst
docs without a hierarchy (that I could notice). So having one sentence included in the intro of the Cross-referencing syntax doc clearly stating the above point and linking back to the roles doc should be enough.
I'm against flattening or merging both documents, it would create a wall-of-text and the current division is already a kind of Sphinx tradition so this reorganization should be enough.
From: https://github.com/sphinx-doc/sphinx/pull/12944#discussion_r1786968351
There's a certain overlap between Cross-referencing syntax and Roles.
The following roles are essentially cross-links but are only mentioned in "Roles":
:manpage:
,:pep:
,:rfc:
,:cve
,:cwe:
Possible solution: Move them from "Roles" to "Cross-referencing syntax" and mention them in https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax.