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

[skoech]

Background

Across the how-to section, we have internal links that have been implemented using the Sphinx :doc: target, e.g. :doc:explanation <../explanation/cluster-configurations>

The implementation works but it is not recommended practice since a change in the folder/file name completely breaks the links and this causes a cascading effect; link checkers will fail and links will break in other repositories linked to the doc. :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 these how-tos with the rST :ref: role:
• Configure cluster network
• Multi-node install
• Enabling Prometheus Alertmanager alerts

Related academy issues

We have created individual issues in the Open Documentation Academy repository:

• https://github.com/canonical/open-documentation-academy/issues/276
• https://github.com/canonical/open-documentation-academy/issues/277
• https://github.com/canonical/open-documentation-academy/issues/279

Resources

• rST cross-referencing standard
• Follow our documentation contributing guide](https://canonical-microceph.readthedocs-hosted.com/latest/contributing/)
• 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.

Thank you in advance for your contribution!

[syncronize-issues-to-jira[bot]]

Thank you for reporting your feedback to us!

The internal ticket has been created: https://warthogs.atlassian.net/browse/CEPH-1421.

This message was autogenerated

[mariaclara-sia]

Hi @skoech, can I work on this as a first issue for my onboarding?

CODA task: https://github.com/canonical/open-documentation-academy/issues/276

[skoech]

@mariaclara-sia, absolutely! Please go ahead, and thank you for your interest. :)