From ed89d7fba5b73c7427be93d15d39ddc4a803030d Mon Sep 17 00:00:00 2001
From: M Bussonnier <bussonniermatthias@gmail.com>
Date: Tue, 11 Jun 2024 15:18:55 +0200
Subject: [PATCH 1/2] DOC: Extend explanation on single vs double backticks.

Add the special case for constant, and try to separate semantic (can
link), to style (monospace, link)

See also #525
---
 doc/format.rst | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/doc/format.rst b/doc/format.rst
index 92cc2d36..d37fcf66 100644
--- a/doc/format.rst
+++ b/doc/format.rst
@@ -753,18 +753,26 @@ monospaced font; in reST, *double* backticks are for ``monospaced font``,
 whereas the behavior of single backticks is defined by the default role. This
 leads to the following style recommendations:
 
-- Module, class, function, method, and attribute names should render as
-  hyperlinks in monospaced font (e.g. :any:`numpy`); depending on project
-  settings, this may be accomplished simply be enclosing them in single
-  backticks. If the hyperlink does not render as intended, explicitly
-  include the appropriate role and/or namespace.
+- Any object that can be linked to should be enclosed in single backticks. That
+  is to say : Module, class, function, method, and attribute names are some of
+  the objects that should be enclosed in single backticks. On a case by cases,
+  instances may also be included in single backticks, like :py:obj:`None`,
+  :py:obj:`True`, :py:obj:`False`.
+
+  These will typically render as hyperlinks in monospaced font (e.g.
+  :any:`numpy`) to the relevant object documentation; depending on project
+  settings. If the hyperlink does not render properly or point to the intended
+  object, explicitly include the appropriate role and/or namespace.
+
 - This guide continues to recommended that parameter names be enclosed within
   single backticks. Currently, this may cause parameter names to render
   improperly and cause warnings, but numpydoc will soon release a feature
   that causes them to render as monospaced hyperlinks to the parameter
   documentation.
-- All other text that is intended to render in ``monospaced`` font should be
-  enclosed within ````double backticks````.
+
+- All other text that is intended to render in ``monospaced`` font and is not
+  supposed to refer to another docs page should be enclosed within ````double
+  backticks````.
 
 A more extensive example of reST markup can be found in `this example
 document <http://docutils.sourceforge.net/docs/user/rst/demo.txt>`_;

From db19b2c45403128e83060b3b9901f00f7c1fc725 Mon Sep 17 00:00:00 2001
From: M Bussonnier <bussonniermatthias@gmail.com>
Date: Tue, 11 Jun 2024 07:05:00 -0700
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: Matt Haberland <mhaberla@calpoly.edu>
---
 doc/format.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/doc/format.rst b/doc/format.rst
index d37fcf66..b7091e21 100644
--- a/doc/format.rst
+++ b/doc/format.rst
@@ -753,9 +753,8 @@ monospaced font; in reST, *double* backticks are for ``monospaced font``,
 whereas the behavior of single backticks is defined by the default role. This
 leads to the following style recommendations:
 
-- Any object that can be linked to should be enclosed in single backticks. That
-  is to say : Module, class, function, method, and attribute names are some of
-  the objects that should be enclosed in single backticks. On a case by cases,
+- For example, module, class, function, method, and attribute names
+  should be enclosed in single backticks. On a case-by-case basis,
   instances may also be included in single backticks, like :py:obj:`None`,
   :py:obj:`True`, :py:obj:`False`.