From 7439d32936b816b5f24dbb3ed886c87bb2b8b7b9 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Mon, 31 Jul 2023 19:10:07 +1000 Subject: [PATCH] doc/start: update linking conventions Update linking conventions in doc/start/documenting-ceph.rst, as requested in https://github.com/ceph/ceph/pull/49889#issuecomment-1657750905 by bluikko. This commit introduces a convention that could be read as inconsistent with other conventions mentioned on the page altered by this commit. Future PRs will attenuate this inconsistency. Signed-off-by: Zac Dover (cherry picked from commit 52e8ec076f7bc65c13f61608b2a4ee0093569947) --- doc/start/documenting-ceph.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst index 3e08846752521..e9336140029fb 100644 --- a/doc/start/documenting-ceph.rst +++ b/doc/start/documenting-ceph.rst @@ -973,6 +973,15 @@ convention was preferred because it made the documents more readable in a command line interface. As of 2023, though, we have no preference for one over the other. Use whichever convention makes the text easier to read. +Using a part of a sentence as a hyperlink, `like this `_, is +discouraged. The convention of writing "See X" is preferred. Here are some +preferred formulations: + +#. For more information, see `docs.ceph.com `_. + +#. See `docs.ceph.com `_. + + Quirks of ReStructured Text --------------------------- -- 2.39.5