crate / crate-docs-theme

A Sphinx theme for the CrateDB documentation.
https://crate-docs-theme.readthedocs.io/
Apache License 2.0
20 stars 5 forks source link

Authoring: Add primer about linking and (cross-) referencing with Sphinx #468

Closed amotl closed 9 months ago

amotl commented 9 months ago

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