Authoring: Add primer about linking and (cross-) referencing with Sphinx #468
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Problem
There hasn't been a clear guide how to define and use the various ways of linking and referencing when writing documentation with Sphinx.
Solution
Now that the system supports both reStructuredText and Markdown, there should be a dedicated page exploring and illustrating all the variants concisely but extensively.
Preview
https://crate-docs-theme--468.org.readthedocs.build/en/468/links.html
Details
This partly builds upon those blocks. When authoring documents, and needing to run links to other parts of the documentation, it is particularly important to be able to quickly find out about available link target labels.
Q&A
Please advise and add any question about linking and referencing in Sphinx you never dared to ask, or add any kind of suggestion where you think we should improve this page. The right time for that is now ;].
/cc @WalBeh, @karynzv, @surister, @wierdvanderhaar