From ed89d7fba5b73c7427be93d15d39ddc4a803030d Mon Sep 17 00:00:00 2001 From: M Bussonnier 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 `_; From db19b2c45403128e83060b3b9901f00f7c1fc725 Mon Sep 17 00:00:00 2001 From: M Bussonnier Date: Tue, 11 Jun 2024 07:05:00 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Matt Haberland --- 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`.