DOC: Clarify recommendations regarding use of backticks (#525)

* doc/format.rst

* Apply suggestions from code review

* MAINT: partially respond to some comments to prepare for discussion

* MAINT: adjustments per review

* MAINT: fix links to numpy

---------

Co-authored-by: Jarrod Millman <jarrod.millman@gmail.com>
Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>

Author: 3 people

doc/conf.py

@@ -139,6 +139,6 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "numpy": ("https://numpy.org/devdocs/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
     "sklearn": ("https://scikit-learn.org/stable/", None),
 }

doc/format.rst

@@ -175,8 +175,9 @@ respective types.
   y
       Description of parameter `y` (with type not specified).
 
-Enclose variables in single backticks.  The colon must be preceded
-by a space, or omitted if the type is absent.
+The colon must be preceded by a space, or omitted if the type is absent.
+When referring to a parameter anywhere within the docstring, enclose its
+name in single backticks.
 
 For the parameter types, be as precise as possible.  Below are a
 few examples of parameters and their types.
@@ -549,6 +550,8 @@ not explicitly imported, `.. plot::` can be used directly if
 Documenting classes
 -------------------
 
+.. _classdoc:
+
 Class docstring
 ```````````````
 Use the same sections as outlined above (all except :ref:`Returns <returns>`
@@ -562,10 +565,12 @@ section, may be used to describe non-method attributes of the class::
   Attributes
   ----------
   x : float
-      The X coordinate.
+      Description of attribute `x`.
   y : float
-      The Y coordinate.
+      Description of attribute `y`.
 
+When referring to an attribute anywhere within the docstring, enclose its
+name in single backticks.
 Attributes that are properties and have their own docstrings can be
 simply listed by name::
 
@@ -606,6 +611,8 @@ becomes useful to have an additional **Methods** section:
 
       """
 
+When referring to a method anywhere within the docstring, enclose its
+name in single backticks.
 If it is necessary to explain a private method (use with care!), it can
 be referred to in the :ref:`Extended Summary <extended_summary>` or the
 :ref:`Notes <notes>` section.
@@ -690,11 +697,11 @@ belong in docstrings.
 Other points to keep in mind
 ----------------------------
 * Equations : as discussed in the :ref:`Notes <notes>` section above, LaTeX
-  formatting should be kept to a minimum.  Often it's possible to show equations as
-  Python code or pseudo-code instead, which is much more readable in a
-  terminal.  For inline display use double backticks (like ``y = np.sin(x)``).
-  For display with blank lines above and below, use a double colon and indent
-  the code, like::
+  formatting should be kept to a minimum.  Often it's possible to show
+  equations as Python code or pseudo-code instead, which is much more readable
+  in a terminal.  For inline display of code, use double backticks
+  like ````y = np.sin(x)````. For display with blank lines above and below,
+  use a double colon and indent the code, like::
 
     end of previous sentence::
 
@@ -717,9 +724,13 @@ Other points to keep in mind
   (i.e. scalar types, sequence types), those arguments can be documented
   with type `array_like`.
 
-* Links : If you need to include hyperlinks in your docstring, note that
-  some docstring sections are not parsed as standard reST, and in these
-  sections, numpydoc may become confused by hyperlink targets such as::
+* Links : Depending on project settings, hyperlinks to documentation of
+  modules, classes, functions, methods, and attributes should automatically
+  be created if a recognized name is included within single backticks (e.g.
+  ```numpy``` renders as :any:`numpy`). If you need to include other
+  hyperlinks, note that some docstring sections are not parsed as standard
+  reST, and in these sections, numpydoc may become confused by hyperlink
+  targets such as::
 
       .. _Example: http://www.example.com
 
@@ -729,17 +740,31 @@ Other points to keep in mind
 
       `Example <http://www.example.com>`_
 
-
 Common reST concepts
 --------------------
 For paragraphs, indentation is significant and indicates indentation in the
 output. New paragraphs are marked with a blank line.
 
-Use ``*italics*``, ``**bold**`` and ````monospace```` if needed in any
-explanations
-(but not for variable names and doctest code or multi-line code).
-Variable, module, function, and class names should be written between
-single back-ticks (```numpy```).
+Use ``*italics*``, ``**bold**`` if needed in any explanations.
+
+Use of backticks in reST is a common point of confusion because it is different
+from markdown. In most flavors of markdown, single backticks are used for
+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.
+- 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````.
 
 A more extensive example of reST markup can be found in `this example
 document <http://docutils.sourceforge.net/docs/user/rst/demo.txt>`_;