Make a dedicated section for cross-reference syntax in docs

[timhoffm]

... and rename the current "Cross-referencing syntax" page to "Cross-references", of which "Syntax" is one subsection.

This section naming fits better to the current content structure. It also allows to distinguish between links to the general cross-referencing topic, and specific links to the syntax.

A small step towards solving #12980.

[AA-Turner]

@timhoffm I sent you an invitation to the Sphinx organisation so that you can edit properties on PRs etc -- let me know if it came through.

A

[timhoffm]

@timhoffm I sent you an invitation to the Sphinx organisation so that you can edit properties on PRs etc -- let me know if it came through.

A

Thanks, I've accepted. Do you have any written guidelines on triaging, or should I just use it (defensively) as I see fit and you correct me if I'm going wrong somewhere?

[AA-Turner]

We have https://www.sphinx-doc.org/en/master/internals/contributing.html but it is somewhat sparse.

Perhaps @picnixz or @jayaddison have thoughts here but my rules of thumb are:

• Apply labels as they make sense, we can add more labels if useful ones are missing
• Milestones are roughly used to track work, but aren't binding
• We don't support old releases, so if an issue can't be reproduced with the latest release then it should be closed
• If an issue is due to an extension then close if not our fault

We should be better at closing issues and rejecting feature requests, but that is often hard.

A

[jayaddison]

I'd mention a few things related to discussions:

• When triaging issues (or perhaps even some pull requests) - try to determine whether the thread is working towards something that can usefully improve Sphinx, or whether they're limitations that the reporter can resolve using existing functionality or adjusting their documentation approach. For the latter, those should probably get redirected to discussion forums (Stackoverflow, GitHub Discussions, sphinx-users email list, ...).
• Also (from experience) when tempted to close something outright, try two or three times more than you might usually to understand why a seemingly-confusing bugreport is talking about something. This takes a long time and sometimes doesn't seem like a good time investment (and arguably could lead to a kind of maintainer/triager ddos), but often there is some underlying detail that isn't easy to figure out without study and/or further conversation in the thread.
• Checking the Sphinx discussion forums occasionally to gather relevant feedback and conversations (I don't do a particularly thorough or systematic job of this, but I check each from time to time).

(probably based on my own biases, experiences and approach, but figured I'd share them anyway)

[electric-coder]

@timhoffm congratulations on becoming a triager. Here are 2 thoughts:

1. Try to always add a language code to every source fence. A lot of users don't know how to do this making their snippets hard to read thus degrading the quality of reports overall.
2. Take a good look at the tag (label) system and use it to retag reports appropriately.