MicroCeph: Replace :doc: with :ref: targets for internal cross-reference links (3) #279
Description
[! IMPORTANT] Notice that this task contains a
workshoplabel; this means that it has been created for the live DjangoCon/Ubucon 2025 Open Documentation Academy workshop to assist community members make their first documentation contribution. Please, do not work on this task unless it is assigned to you.
Background
In the Enabling Prometheus Alertmanager alerts, how-to, we have an internal link to the how-to section. This link has been implemented using the Sphinx :doc: target, i.e. Follow :doc:this How-To `
This implementation works but it is not recommended practice since a change in the folder/file name would completely break the link and this would cause link checks to fail, and links to the document to break in other repositories to break. :doc: is fragile, and will break!
The benefit of using :ref: is that the target remains the same even if you change the file's location or name. Also, if you use :ref: with an anchor, you can cross-ref to a specific part of the document, :doc:.
Task
- Replace the
:doc:target in the last line of the Enabling Prometheus Alertmanager alerts how-to, with the:ref:MyST target. - Follow the recommended MyST cross-referencing standard to update the link.
Resources
- MyST cross-referencing standard
- Follow our documentation contributing guide
- Read the Ubuntu Code of Conduct.
- Visit the academy website
[!NOTE] The current implementation uses a relative link to access the page whilst the second implementation links to the cross-reference header in the file. This means that the link will always work even in the event that we change the file name or move it to another folder.
[!NOTE] Please claim the task here, but please work under canonical/microceph#605 to get help and feedback from the team.
Thank you in advance for your contribution!