From a2f5e242c4e9dba6804226f0d81dc5ae1118bd98 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Mon, 2 Jan 2023 14:23:22 +1000 Subject: [PATCH] doc/start: refine "Quirks of RST" Refine the language that was added yesterday, language that explains how certain aspects of RST work. Signed-off-by: Zac Dover (cherry picked from commit cdc7b6035414ea46b1e583d21a3a821f041c5417) --- doc/start/documenting-ceph.rst | 35 ++++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst index 332952691f62b..b9530374b7b9e 100644 --- a/doc/start/documenting-ceph.rst +++ b/doc/start/documenting-ceph.rst @@ -668,6 +668,8 @@ the ``.rst`` source files will work even if the source files are moved within the ``ceph/doc`` directory. See `Cross referencing arbitrary locations`_ for details. +.. _start_external_hyperlink_example: + External Hyperlink Example ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -680,12 +682,14 @@ For example, RST that links to the Sphinx Python Document Generator homepage and generates a sentence reading "Click here to learn more about Python Sphinx." looks like this: -* ``Click `here `_ to learn more about Python - Sphinx.`` +:: + + ``Click `here `_ to learn more about Python + Sphinx.`` And here it is, rendered: -* Click `here `_ to learn more about Python Sphinx. +Click `here `_ to learn more about Python Sphinx. Pay special attention to the underscore after the backtick. If you forget to include it and this is your first day working with RST, there's a chance that @@ -725,20 +729,22 @@ This is the formula for links to addresses external to the Ceph documentation: Do not fail to include the underscore after the final backtick. - The convention for linking to addresses external to the Ceph documentation - and defining inline text is a convention that includes a space between the - inline text and the less-than sign that precedes the external address. This - is precisely the opposite of :ref:`the convention for inline text that links - to a location inside the Ceph - documentation`. + To link to addresses that are external to the Ceph documentation, you have + to include a space between the inline text and the angle bracket that + precedes the external address. This is precisely the opposite of :ref:`the + convention for inline text that links to a location inside the Ceph + documentation`. If this seems inconsistent + and confusing to you, then you're right. It is inconsistent and confusing. +See also ":ref:`External Hyperlink Example`". Internal Links ~~~~~~~~~~~~~~ -To link to a section in the Ceph documentation, you must define a target link -before the section and then link to that target from another location in the -documentation. Here are the formulas for targets and links to those targets: +To link to a section that is in the Ceph documentation, you must (1) define a +target link before the section and then (2) link to that target from another +location in the documentation. Here are the formulas for targets and links to +those targets: Target:: @@ -761,10 +767,11 @@ Link to target with inline text:: .. note:: - There is no space between "inline text" and the less-than sign that + There is no space between "inline text" and the angle bracket that immediately follows it. This is precisely the opposite of :ref:`the convention for inline text that links to a location outside of the Ceph - documentation`. + documentation`. If this seems inconsistent + and confusing to you, then you're right. It is inconsistent and confusing. .. _Python Sphinx: https://www.sphinx-doc.org -- 2.39.5