MicroCeph: Replace :doc: with :ref: targets for internal cross-reference links (2)

Background

The MicroCeph how-to guide for installing a multi-node cluster, has an internal link, under the "Manage the cluster" subsection, to the general how-to landing page. This link has been implemented using the Sphinx :doc: target, i.e. :doc:Howto <../how-to/index>`

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 identified internal link in the installing a multi-node cluster how-to with the rST :ref: role.
• Follow the recommended rST cross-referencing standard to update the link.
• In order to use :ref:, you need to use labels with the .. _some-label: syntax above the header you want to link to/reference
• :ref: and labels work hand in hand: the label creates the target, then the :ref: links to that target

Resources

• rST 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 https://github.com/canonical/microceph/issues/605 to get help and feedback from the team.

Thank you in advance for your contribution!