Merge pull request #16510 from anntzer/docmarkup

jklymak · web-flow · commit 5f555f8ab680 · 2020-02-14T08:55:35.000-08:00
Doc markup cleanups.
diff --git a/doc/users/dflt_style_changes.rst b/doc/users/dflt_style_changes.rst
@@ -95,7 +95,7 @@ abbreviated style string in ``plot``, however the new default colors
 are only specified via hex values.  To access these colors outside of
 the property cycling the notation for colors ``'CN'``, where ``N``
 takes values 0-9, was added to
-denote the first 10 colors in ``mpl.rcParams['axes.prop_cycle']`` See
+denote the first 10 colors in :rc:`axes.prop_cycle`. See
 :doc:`/tutorials/colors/colors` for more details.
 
 To restore the old color cycle use
@@ -1130,7 +1130,7 @@ but cannot be controlled independently via `.rcParams`.
 ``ScalarFormatter`` tick label formatting with offsets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-With the default of ``rcParams['axes.formatter.useoffset'] = True``,
+With the default :rc:`axes.formatter.useoffset`,
 an offset will be used when it will save 4 or more digits.  This can
 be controlled with the new :rc:`axes.formatter.offset_threshold`.
 To restore the previous behavior of using an offset to save 2 or more
diff --git a/doc/users/next_whats_new/2019-10-18_rcParams-for-raise-window-behavior.rst b/doc/users/next_whats_new/2019-10-18_rcParams-for-raise-window-behavior.rst
@@ -2,7 +2,7 @@
 
 rcParams for controlling default "raise window" behavior
 --------------------------------------------------------
-The new config option ``rcParams['figure.raise_window']`` allows to disable
-raising the plot window when calling ``plt.show`` or ``plt.pause`` methods.
+The new config option :rc:`figure.raise_window` allows to disable
+raising the plot window when calling `~.pyplot.show` or `~.pyplot.pause`.
 ``MacOSX`` backend is currently not supported.
 
diff --git a/examples/color/color_demo.py b/examples/color/color_demo.py
@@ -16,9 +16,9 @@
 6) a name from the `xkcd color survey <https://xkcd.com/color/rgb/>`__,
    prefixed with ``'xkcd:'`` (e.g., ``'xkcd:sky blue'``);
 7) a "Cn" color spec, i.e. ``'C'`` followed by a number, which is an index into
-   the default property cycle (``matplotlib.rcParams['axes.prop_cycle']``); the
-   indexing is intended to occur at rendering time, and defaults to black if
-   the cycle does not include color.
+   the default property cycle (:rc:`axes.prop_cycle`); the indexing is intended
+   to occur at rendering time, and defaults to black if the cycle does not
+   include color.
 8) one of ``{'tab:blue', 'tab:orange', 'tab:green',
    'tab:red', 'tab:purple', 'tab:brown', 'tab:pink',
    'tab:gray', 'tab:olive', 'tab:cyan'}`` which are the Tableau Colors from the
diff --git a/examples/pyplots/fig_axes_customize_simple.py b/examples/pyplots/fig_axes_customize_simple.py
@@ -9,7 +9,7 @@
 import matplotlib.pyplot as plt
 
 ###############################################################################
-# ``plt.figure`` creates a ```matplotlib.figure.Figure`` instance
+# `.pyplot.figure` creates a `matplotlib.figure.Figure` instance.
 
 fig = plt.figure()
 rect = fig.patch  # a rectangle instance
diff --git a/tutorials/advanced/transforms_tutorial.py b/tutorials/advanced/transforms_tutorial.py
@@ -547,7 +547,7 @@
 # ``transProjection`` handles the projection from the space,
 # e.g., latitude and longitude for map data, or radius and theta for polar
 # data, to a separable Cartesian coordinate system.  There are several
-# projection examples in the ``matplotlib.projections`` package, and the
+# projection examples in the :mod:`matplotlib.projections` package, and the
 # best way to learn more is to open the source for those packages and
 # see how to make your own, since Matplotlib supports extensible axes
 # and projections.  Michael Droettboom has provided a nice tutorial
diff --git a/tutorials/colors/colors.py b/tutorials/colors/colors.py
@@ -26,9 +26,9 @@
   'tab:purple', 'tab:brown', 'tab:pink', 'tab:gray', 'tab:olive', 'tab:cyan'}``
   (case-insensitive);
 * a "CN" color spec, i.e. ``'C'`` followed by a number, which is an index into
-  the default property cycle (``matplotlib.rcParams['axes.prop_cycle']``); the
-  indexing is intended to occur at rendering time, and defaults to black if the
-  cycle does not include color.
+  the default property cycle (:rc:`axes.prop_cycle`); the indexing is intended
+  to occur at rendering time, and defaults to black if the cycle does not
+  include color.
 
 .. _xkcd color survey: https://xkcd.com/color/rgb/
 
@@ -81,7 +81,7 @@ def demo(sty):
 
 ###############################################################################
 # will use the first color for the title and then plot using the second
-# and third colors of each style's ``mpl.rcParams['axes.prop_cycle']``.
+# and third colors of each style's :rc:`axes.prop_cycle`.
 #
 #
 # .. _xkcd-colors:
diff --git a/tutorials/intermediate/color_cycle.py b/tutorials/intermediate/color_cycle.py
@@ -67,12 +67,11 @@
 plt.show()
 
 ###############################################################################
-# Setting ``prop_cycle`` in the ``matplotlibrc`` file or style files
-# ------------------------------------------------------------------
+# Setting ``prop_cycle`` in the :file:`matplotlibrc` file or style files
+# ----------------------------------------------------------------------
 #
-# Remember, if you want to set a custom cycler in your
-# ``.matplotlibrc`` file or a style file (``style.mplstyle``), you can set the
-# ``axes.prop_cycle`` property:
+# Remember, a custom cycler can be set in your :file:`matplotlibrc`
+# file or a style file (:file:`style.mplstyle`) under ``axes.prop_cycle``:
 #
 # .. code-block:: python
 #
diff --git a/tutorials/intermediate/tight_layout_guide.py b/tutorials/intermediate/tight_layout_guide.py
@@ -58,7 +58,7 @@ def example_plot(ax, fontsize=12):
 # Note that :func:`matplotlib.pyplot.tight_layout` will only adjust the
 # subplot params when it is called.  In order to perform this adjustment each
 # time the figure is redrawn, you can call ``fig.set_tight_layout(True)``, or,
-# equivalently, set the ``figure.autolayout`` rcParam to ``True``.
+# equivalently, set :rc:`figure.autolayout` to ``True``.
 #
 # When you have multiple subplots, often you see labels of different
 # axes overlapping each other.
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -290,15 +290,15 @@ def my_plotter(ax, data1, data2, param_dict):
 #
 # There are three ways to configure your backend:
 #
-# 1. The :rc:`backend` parameter in your ``matplotlibrc`` file
+# 1. The :rc:`backend` parameter in your :file:`matplotlibrc` file
 # 2. The :envvar:`MPLBACKEND` environment variable
 # 3. The function :func:`matplotlib.use`
 #
 # A more detailed description is given below.
 #
 # If multiple of these are configurations are present, the last one from the
 # list takes precedence; e.g. calling :func:`matplotlib.use()` will override
-# the setting in your ``matplotlibrc``.
+# the setting in your :file:`matplotlibrc`.
 #
 # If no backend is explicitly set, Matplotlib automatically detects a usable
 # backend based on what is available on your system and on whether a GUI event
@@ -308,7 +308,7 @@ def my_plotter(ax, data1, data2, param_dict):
 #
 # Here is a detailed description of the configuration methods:
 #
-# #. Setting :rc:`backend` in your ``matplotlibrc`` file::
+# #. Setting :rc:`backend` in your :file:`matplotlibrc` file::
 #
 #        backend : qt5agg   # use pyqt5 with antigrain (agg) rendering
 #
@@ -332,10 +332,10 @@ def my_plotter(ax, data1, data2, param_dict):
 #         > python simple_plot.py
 #
 #    Setting this environment variable will override the ``backend`` parameter
-#    in *any* ``matplotlibrc``, even if there is a ``matplotlibrc`` in your
-#    current working directory. Therefore, setting :envvar:`MPLBACKEND`
-#    globally, e.g. in your ``.bashrc`` or ``.profile``, is discouraged as it
-#    might lead to counter-intuitive behavior.
+#    in *any* :file:`matplotlibrc`, even if there is a :file:`matplotlibrc` in
+#    your current working directory. Therefore, setting :envvar:`MPLBACKEND`
+#    globally, e.g. in your :file:`.bashrc` or :file:`.profile`, is discouraged
+#    as it might lead to counter-intuitive behavior.
 #
 # #. If your script depends on a specific backend you can use the function
 #    :func:`matplotlib.use`::
@@ -646,18 +646,15 @@ def my_plotter(ax, data1, data2, param_dict):
 # Line segment simplification
 # ---------------------------
 #
-# For plots that have line segments (e.g. typical line plots,
-# outlines of polygons, etc.), rendering performance can be
-# controlled by the ``path.simplify`` and
-# ``path.simplify_threshold`` parameters in your
-# ``matplotlibrc`` file (see
-# :doc:`/tutorials/introductory/customizing` for
-# more information about the ``matplotlibrc`` file).
-# The ``path.simplify`` parameter is a boolean indicating whether
-# or not line segments are simplified at all. The
-# ``path.simplify_threshold`` parameter controls how much line
-# segments are simplified; higher thresholds result in quicker
-# rendering.
+# For plots that have line segments (e.g. typical line plots, outlines
+# of polygons, etc.), rendering performance can be controlled by
+# :rc:`path.simplify` and :rc:`path.simplify_threshold`, which
+# can be defined e.g. in the :file:`matplotlibrc` file (see
+# :doc:`/tutorials/introductory/customizing` for more information about
+# the :file:`matplotlibrc` file). :rc:`path.simplify` is a boolean
+# indicating whether or not line segments are simplified at all.
+# :rc:`path.simplify_threshold` controls how much line segments are simplified;
+# higher thresholds result in quicker rendering.
 #
 # The following script will first display the data without any
 # simplification, and then display the same data with simplification.
@@ -683,7 +680,7 @@ def my_plotter(ax, data1, data2, param_dict):
 #
 # Matplotlib currently defaults to a conservative simplification
 # threshold of ``1/9``. If you want to change your default settings
-# to use a different value, you can change your ``matplotlibrc``
+# to use a different value, you can change your :file:`matplotlibrc`
 # file.  Alternatively, you could create a new style for
 # interactive plotting (with maximal simplification) and another
 # style for publication quality plotting (with minimal
diff --git a/tutorials/text/annotations.py b/tutorials/text/annotations.py
@@ -329,11 +329,11 @@
 Placing Artist at the anchored location of the Axes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are classes of artists that can be placed at an anchored location
-in the Axes. A common example is the legend.  This type of artist can
-be created by using the OffsetBox class. A few predefined classes are
-available in ``mpl_toolkits.axes_grid1.anchored_artists`` others in
-``matplotlib.offsetbox`` ::
+There are classes of artists that can be placed at an anchored
+location in the Axes.  A common example is the legend.  This type
+of artist can be created by using the `.OffsetBox` class. A few
+predefined classes are available in :mod:`matplotlib.offsetbox` and in
+:mod:`mpl_toolkits.axes_grid1.anchored_artists`. ::
 
     from matplotlib.offsetbox import AnchoredText
     at = AnchoredText("Figure 1a",

Original file line number	Diff line number	Diff line change
`@@ -67,12 +67,11 @@`
`67`	`67`	`plt.show()`
`68`	`68`
`69`	`69`	`###############################################################################`
`70`		-# Setting ``prop_cycle`` in the ``matplotlibrc`` file or style files
`71`		`-# ------------------------------------------------------------------`
	`70`	+# Setting ``prop_cycle`` in the :file:`matplotlibrc` file or style files
	`71`	`+# ----------------------------------------------------------------------`
`72`	`72`	`#`
`73`		`-# Remember, if you want to set a custom cycler in your`
`74`		-# ``.matplotlibrc`` file or a style file (``style.mplstyle``), you can set the
`75`		-# ``axes.prop_cycle`` property:
	`73`	+# Remember, a custom cycler can be set in your :file:`matplotlibrc`
	`74`	+# file or a style file (:file:`style.mplstyle`) under ``axes.prop_cycle``:
`76`	`75`	`#`
`77`	`76`	`# .. code-block:: python`
`78`	`77`	`#`
Original file line number	Diff line number	Diff line change
`@@ -58,7 +58,7 @@ def example_plot(ax, fontsize=12):`
`58`	`58`	# Note that :func:`matplotlib.pyplot.tight_layout` will only adjust the
`59`	`59`	`# subplot params when it is called. In order to perform this adjustment each`
`60`	`60`	# time the figure is redrawn, you can call ``fig.set_tight_layout(True)``, or,
`61`		-# equivalently, set the ``figure.autolayout`` rcParam to ``True``.
	`61`	+# equivalently, set :rc:`figure.autolayout` to ``True``.
`62`	`62`	`#`
`63`	`63`	`# When you have multiple subplots, often you see labels of different`
`64`	`64`	`# axes overlapping each other.`