Untangle Roles and Cross-referencing syntax docs

[timhoffm]

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.

[electric-coder]

This issue takes some deep thinking and comprehensively writing the doc won't be easy.

[timhoffm]

Unordered thoughts that may need consideration:

• We have to groups of references:

  1. direct children of ReferenceRole: CVE, CWE, PEP, RFC, Manpage, IndexRole
  2. children of the subclass 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.

[electric-coder]

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

  • Domain cross-referencing See Domains for declarations that can be cross-referenced and the specific roles used to cross-reference them.

  • 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.