Merge pull request matplotlib#18372 from QuLogic/doc-refs

DOC: Fix various missing references and typos

Author: story645

doc/api/docstring_api.rst

@@ -0,0 +1,8 @@
+************************
+``matplotlib.docstring``
+************************
+
+.. automodule:: matplotlib.docstring
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/index.rst

@@ -87,6 +87,7 @@ Matplotlib consists of the following submodules:
    container_api.rst
    contour_api.rst
    dates_api.rst
+   docstring_api.rst
    dviread.rst
    figure_api.rst
    font_manager_api.rst

doc/api/prev_api_changes/api_changes_3.1.0.rst

@@ -767,11 +767,12 @@ The following signature related behaviours are deprecated:
   keyword.
 - The *interp_at_native* parameter to `.BboxImage`, which has had no effect
   since Matplotlib 2.0, is deprecated.
-- All arguments to the `.cbook.deprecated` decorator and `.cbook.warn_deprecated`
-  function, except the first one (the version where the deprecation occurred),
-  are now keyword-only.  The goal is to avoid accidentally setting the "message"
-  argument when the "name" (or "alternative") argument was intended, as this has
-  repeatedly occurred in the past.
+- All arguments to the `~.cbook.deprecation.deprecated` decorator and
+  `~.cbook.deprecation.warn_deprecated` function, except the first one (the
+  version where the deprecation occurred), are now keyword-only.  The goal is
+  to avoid accidentally setting the "message" argument when the "name" (or
+  "alternative") argument was intended, as this has repeatedly occurred in the
+  past.
 - The arguments of `matplotlib.testing.compare.calculate_rms` have been renamed
   from ``expectedImage, actualImage``, to ``expected_image, actual_image``.
 - Passing positional arguments to `.Axis.set_ticklabels` beyond *ticklabels*
@@ -1073,11 +1074,12 @@ This only served as a helper to the private `.Axis._update_ticks`
 
 Undeprecations
 --------------
-The following API elements have bee un-deprecated:
+The following API elements have been un-deprecated:
 
-- The *obj_type* kwarg to the `.cbook.deprecated` decorator.
-- *xmin*, *xmax* kwargs to `.Axes.set_xlim` and *ymin*, *ymax* kwargs
-  to `.Axes.set_ylim`
+- The *obj_type* keyword argument to the `~.cbook.deprecation.deprecated`
+  decorator.
+- *xmin*, *xmax* keyword arguments to `.Axes.set_xlim` and *ymin*, *ymax*
+  keyword arguments to `.Axes.set_ylim`
 
 
 New features

doc/api/testing_api.rst

@@ -3,6 +3,11 @@
 **********************
 
 
+:func:`matplotlib.test`
+=======================
+
+.. autofunction:: matplotlib.test
+
 :mod:`matplotlib.testing`
 =========================
 

doc/devel/MEP/MEP10.rst

@@ -159,15 +159,15 @@ Implementation
    should be divided on a per-module basis so no single developer is
    over-burdened by it.
 
-3. Reorganize the API docs using autosummary and `sphinx-autogen`.
+3. Reorganize the API docs using autosummary and ``sphinx-autogen``.
    This should hopefully have minimal impact on the narrative
    documentation.
 
 4. Modify the example page generator (:file:`gen_rst.py`) so that it
    extracts the module docstring from the example and includes it in a
    non-literal part of the example page.
 
-5. Use `sphinx-quickstart` to generate a new-style Sphinx Makefile.
+5. Use ``sphinx-quickstart`` to generate a new-style Sphinx Makefile.
    The following features in the current :file:`make.py` will have to be
    addressed in some other way:
 

doc/devel/MEP/MEP12.rst

@@ -11,7 +11,8 @@ Status
 **Progress**
 
 Initial changes added in 1.3. Conversion of the gallery is on-going.
-29 September 2015 - The last ``pylab_examples`` where `pylab` is imported has been converted over to use :mod:`matplotlib.pyplot` and `numpy`.
+29 September 2015 - The last ``pylab_examples`` where ``pylab`` is imported has
+been converted over to use :mod:`matplotlib.pyplot` and `numpy`.
 
 Branches and Pull requests
 ==========================

doc/devel/MEP/MEP14.rst

@@ -265,16 +265,16 @@ Implementation
 ==============
 
 A concept of a "text engine" will be introduced.  Each text engine
-will implement a number of abstract classes.  The `TextFont` interface
+will implement a number of abstract classes.  The ``TextFont`` interface
 will represent text for a given set of font properties.  It isn't
 necessarily limited to a single font file -- if the layout engine
 supports rich text, it may handle a number of font files in a family.
-Given a `TextFont` instance, the user can get a `TextLayout` instance,
+Given a ``TextFont`` instance, the user can get a ``TextLayout`` instance,
 which represents the layout for a given string of text in a given
-font.  From a `TextLayout`, an iterator over `TextSpans` is returned
+font.  From a ``TextLayout``, an iterator over ``TextSpan``\ s is returned
 so the engine can output raw editable text using as few spans as
 possible.  If the engine would rather get individual characters, they
-can be obtained from the `TextSpan` instance::
+can be obtained from the ``TextSpan`` instance::
 
 
   class TextFont(TextFontBase):
@@ -376,10 +376,10 @@ copy of the path for each character will be stored in the file.
 Special casing: The "usetex" functionality currently is able to get
 Postscript directly from TeX to insert directly in a Postscript file,
 but for other backends, parses a DVI file and generates something more
-abstract.  For a case like this, `TextLayout` would implement
-`get_spans` for most backends, but add `get_ps` for the Postscript
+abstract.  For a case like this, ``TextLayout`` would implement
+``get_spans`` for most backends, but add ``get_ps`` for the Postscript
 backend, which would look for the presence of this method and use it
-if available, or fall back to `get_spans`.  This kind of special
+if available, or fall back to ``get_spans``.  This kind of special
 casing may also be necessary, for example, when the graphics backend
 and text engine belong to the same ecosystem, e.g. Cairo and Pango, or
 MacOSX and CoreText.

doc/devel/MEP/MEP15.rst

@@ -18,9 +18,9 @@ None so far.
 Abstract
 ========
 
-When one axis of a 2-dimensional plot if overridden via `~.Axes.set_xlim` or `~.Axes.set_ylim`,
-automatic scaling of the remaining axis should be based on the data that falls
-within the specified limits of the first axis.
+When one Axis of a 2-dimensional plot is overridden via `~.Axes.set_xlim` or
+`~.Axes.set_ylim`, automatic scaling of the remaining Axis should be based on
+the data that falls within the specified limits of the first Axis.
 
 Detailed description
 ====================

doc/devel/MEP/MEP22.rst

@@ -39,7 +39,7 @@ reconfiguration.
 
 This approach will make easier to create and share tools among
 users. In the far future, we can even foresee a kind of Marketplace
-for `Tools` where the most popular can be added into the main
+for ``Tool``\ s where the most popular can be added into the main
 distribution.
 
 Detailed description
@@ -53,12 +53,12 @@ example see https://github.com/matplotlib/matplotlib/issues/2694 also
 the shortcuts are hardcoded and again not easily modifiable
 https://github.com/matplotlib/matplotlib/issues/2699
 
-The proposed solution is to take the actions out of the `Toolbar` and
-the shortcuts out of the `Canvas`.  This actions and shortcuts will be
-in the form of `Tools`.
+The proposed solution is to take the actions out of the ``Toolbar`` and the
+shortcuts out of the ``Canvas``. The actions and shortcuts will be in the form
+of ``Tool``\ s.
 
-A new class `Navigation` will be the bridge between the events from
-the `Canvas` and `Toolbar` and redirect them to the appropriate `Tool`.
+A new class ``Navigation`` will be the bridge between the events from the
+``Canvas`` and ``Toolbar`` and redirect them to the appropriate ``Tool``.
 
 At the end the user interaction will be divided into three classes:
 
@@ -75,7 +75,8 @@ Implementation
 ToolBase(object)
 ----------------
 
-Tools can have a graphical representation as the `SubplotTool` or not even be present in the Toolbar as `Quit`
+Tools can have a graphical representation as the ``SubplotTool`` or not even be
+present in the Toolbar as ``Quit``.
 
 The `.ToolBase` has the following class attributes for configuration at definition time
 
@@ -93,7 +94,8 @@ The following instance attributes are set at instantiation:
    * keypress associated with the Tool Keymap
    * Call to navigation.trigger_tool(name)
  * set_figure(self, figure): Set the figure and navigation attributes
- * ``destroy(self, *args)``: Destroy the `Tool` graphical interface (if exists)
+ * ``destroy(self, *args)``: Destroy the ``Tool`` graphical interface (if
+   exists)
 
 **Available Tools**
  * ToolQuit
@@ -137,7 +139,7 @@ NavigationBase
 
 Defines the following attributes
  * canvas:
- * keypresslock: Lock to know if the `canvas` key_press_event` is
+ * keypresslock: Lock to know if the ``canvas`` ``key_press_event`` is
         available and process it
  * messagelock: Lock to know if the message is available to write
 
@@ -152,9 +154,9 @@ Public methods for **User use**:
    associated with the tool
  * set_tool_keymap(self, name, ``*keys``): Set the keys for the given tool
  * remove_tool(self, name): Removes tool from the navigation control.
- * add_tools(self, tools): Add multiple tools to `Navigation`
+ * add_tools(self, tools): Add multiple tools to ``Navigation``
  * add_tool(self, name, tool, group=None, position=None): Add a tool
-   to the Navigation
+   to the ``Navigation``
  * tool_trigger_event(self, name, sender=None, canvasevent=None,
    data=None): Trigger a tool and fire the event
 
@@ -168,20 +170,20 @@ ToolbarBase
 -----------
 
 Methods for **Backend implementation**
- * add_toolitem(self, name, group, position, image, description,
-   toggle): Add a toolitem to the toolbar. This method is a callback
-   from `tool_added_event` (emitted by navigation)
- * set_message(self, s): Display a message on toolbar or in status bar
- * toggle_toolitem(self, name): Toggle the toolitem without firing
-   event.
- * remove_toolitem(self, name): Remove a toolitem from the `Toolbar`
+
+* ``add_toolitem(self, name, group, position, image, description, toggle)``:
+  Add a toolitem to the toolbar. This method is a callback from
+  ``tool_added_event`` (emitted by navigation)
+* ``set_message(self, s)``: Display a message on toolbar or in status bar
+* ``toggle_toolitem(self, name)``: Toggle the toolitem without firing event.
+* ``remove_toolitem(self, name)``: Remove a toolitem from the ``Toolbar``
 
 
 Backward compatibility
 ======================
 
 For backward compatibility added 'navigation' to the list of values
-supported by :rc:`toolbar`, that is used for Navigation classes
+supported by :rc:`toolbar`, that is used for ``Navigation`` classes
 instantiation instead of the NavigationToolbar classes
 
 With this parameter, it makes it transparent to anyone using the

doc/devel/MEP/MEP23.rst

@@ -23,7 +23,7 @@ Abstract
 ========
 
 Add the possibility to have multiple figures grouped under the same
-`FigureManager`
+`~.backend_template.FigureManager`
 
 Detailed description
 ====================
@@ -38,60 +38,65 @@ desirable to be able to group these under the same window
 [see](https://github.com/matplotlib/matplotlib/issues/2194).
 
 The proposed solution modifies `.FigureManagerBase` to contain and manage more
-than one `canvas`.  The settings parameter :rc:`backend.multifigure` control
+than one ``Canvas``. The settings parameter :rc:`backend.multifigure` control
 when the **MultiFigure** behaviour is desired.
 
 **Note**
 
 It is important to note, that the proposed solution, assumes that the
 [MEP22](https://github.com/matplotlib/matplotlib/wiki/Mep22) is
 already in place. This is simply because the actual implementation of
-the `Toolbar` makes it pretty hard to switch between canvases.
+the ``Toolbar`` makes it pretty hard to switch between canvases.
 
 Implementation
 ==============
 
 The first implementation will be done in GTK3 using a Notebook as
 canvas container.
 
-`.FigureManagerBase`
---------------------
+``FigureManagerBase``
+---------------------
 
 will add the following new methods
 
-* `add_canvas`: To add a canvas to an existing `FigureManager` object
-* `remove_canvas`: To remove a canvas from a `FigureManager` object,
-  if it is the last one, it will be destroyed
-* `move_canvas`: To move a canvas from one `FigureManager` to another.
-* `set_canvas_title`: To change the title associated with a specific
+* ``add_canvas``: To add a canvas to an existing
+  `~.backend_template.FigureManager` object
+* ``remove_canvas``: To remove a canvas from a
+  `~.backend_template.FigureManager` object, if it is the last one, it will be
+  destroyed
+* ``move_canvas``: To move a canvas from one `~.backend_template.FigureManager`
+  to another.
+* ``set_canvas_title``: To change the title associated with a specific
   canvas container
-* `get_canvas_title`: To get the title associated with a specific
+* ``get_canvas_title``: To get the title associated with a specific
   canvas container
-* `get_active_canvas`: To get the canvas that is in the foreground and
-  is subject to the gui events. There is no `set_active_canvas`
-  because the active canvas, is defined when `show` is called on a
-  `Canvas` object.
+* ``get_active_canvas``: To get the canvas that is in the foreground and
+  is subject to the gui events. There is no ``set_active_canvas``
+  because the active canvas, is defined when ``show`` is called on a
+  ``Canvas`` object.
 
-`new_figure_manager`
---------------------
+``new_figure_manager``
+----------------------
 
-To control which `FigureManager` will contain the new figures, an
-extra optional parameter *figuremanager* will be added, this parameter
-value will be passed to `new_figure_manager_given_figure`
+To control which `~.backend_template.FigureManager` will contain the new
+figures, an extra optional parameter *figuremanager* will be added, this
+parameter value will be passed to ``new_figure_manager_given_figure``.
 
-`new_figure_manager_given_figure`
----------------------------------
+``new_figure_manager_given_figure``
+-----------------------------------
 
-* If *figuremanager* parameter is given, this `FigureManager` object
-  will be used instead of creating a new one.
+* If *figuremanager* parameter is given, this
+  `~.backend_template.FigureManager` object will be used instead of creating a
+  new one.
 * If ``rcParams['backend.multifigure']`` is True: The last
-  `FigureManager` object will be used instead of creating a new one.
+  `~.backend_template.FigureManager` object will be used instead of creating a
+  new one.
 
-`NavigationBase`
-----------------
+``NavigationBase``
+------------------
 
-Modifies the `NavigationBase` to keep a list of canvases, directing
-the actions to the active one
+Modifies the ``NavigationBase`` to keep a list of canvases, directing the
+actions to the active one.
 
 Backward compatibility
 ======================