DOC: Clarify recommendations regarding use of backticks

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,12 @@ 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 : Sphinx will automatically create hyperlinks to module, function,
+  and class documentation if a recognized name is included within single
+  backticks (e.g. ```numpy``` renders as `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 +739,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 recommendations:
+
+- Module, function, and class names should render as hyperlinks in monospaced
+  font (e.g. `numpy`), and depending on project settings, it may be sufficient
+  to enclose them in single backticks. If the hyperlink does not render as
+  intended, explicitly include the appropriate role and/or namespace.
+- References to parameters, attributes, and methods defined within the same
+  docstring should also render as hyperlinks in monospaced font. Unless the
+  default role is reconfigured, the recommendation is to enclosed these within
+  ```single backticks```. These typically render as broken links (commonly
+  in *italics*), but there are plans to render a ``monospaced`` hyperlink in
+  a future version of numpydoc.
+- 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>`_;