From: Zac Dover Date: Mon, 31 Jul 2023 09:10:07 +0000 (+1000) Subject: doc/start: update linking conventions X-Git-Tag: v17.2.7~211^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F52913%2Fhead;p=ceph.git 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) --- diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst index 3e0884675252..e9336140029f 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 ---------------------------