From: Zac Dover <zac.dover@gmail.com>
Date: Sun, 1 Jan 2023 12:06:54 +0000 (+1000)
Subject: doc/start: add link-related metadocumentation
X-Git-Tag: v18.1.0~571^2
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=7517404f72819907700036cd1a287174bad38f10;p=ceph-ci.git

doc/start: add link-related metadocumentation

Add two kinds of link-related metadocumentation (documentation about how
to write documentation) to the "Documenting Ceph" section of the "Intro
to Ceph" document: 1. metadocumentation about external links, and 2.
metadocumentation about internal links.

Signed-off-by: Zac Dover <zac.dover@gmail.com>
---

diff --git a/doc/start/documenting-ceph.rst b/doc/start/documenting-ceph.rst
index 437204cd117..aefb4291d2a 100644
--- a/doc/start/documenting-ceph.rst
+++ b/doc/start/documenting-ceph.rst
@@ -706,6 +706,66 @@ 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.
 
+Quirks of ReStructured Text
+---------------------------
+
+External Links
+~~~~~~~~~~~~~~
+
+.. _external_link_with_inline_text:
+
+This is the formula for links to addresses external to the Ceph documentation:
+
+::
+
+   `inline text <http:www.foo.com>`_
+
+.. note:: Do not fail to include the space between the inline text and the
+   less-than sign. 
+   
+   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<internal_link_with_inline_text>`. 
+
+
+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:
+
+Target::
+
+   .. _target:
+
+   Title of Targeted Section
+   =========================
+
+   Lorem ipsum...
+
+Link to target::
+
+   :ref:`target`
+
+.. _internal_link_with_inline_text:
+
+Link to target with inline text::
+
+   :ref:`inline text<target>`
+
+.. note:: 
+
+   There is no space between "inline text" and the less-than sign 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<external_link_with_inline_text>`. 
+
 
 .. _Python Sphinx: https://www.sphinx-doc.org
 .. _restructuredText: http://docutils.sourceforge.net/rst.html