Fix some broken doc refs.

Author: anntzer

doc/api/prev_api_changes/api_changes_3.0.0.rst

@@ -302,11 +302,11 @@ being incorrectly modified by these functions.
 
 
 
-`CallbackRegistry` now stores callbacks using stdlib's `WeakMethod`\s
----------------------------------------------------------------------
+`CallbackRegistry` now stores callbacks using stdlib's `.WeakMethod`\s
+----------------------------------------------------------------------
 
 In particular, this implies that ``CallbackRegistry.callbacks[signal]`` is now
-a mapping of callback ids to `WeakMethod`\s (i.e., they need to be first called
+a mapping of callback ids to `.WeakMethod`\s (i.e., they need to be first called
 with no arguments to retrieve the method itself).
 
 
@@ -544,8 +544,8 @@ Proprietary sphinx directives
 `````````````````````````````
 
 The matplotlib documentation used the proprietary sphinx directives
-`.. htmlonly::`, and `.. latexonly::`. These have been replaced with the
-standard sphinx directives `.. only:: html` and `.. only:: latex`. This
+``.. htmlonly::``, and ``.. latexonly::``. These have been replaced with the
+standard sphinx directives ``.. only:: html`` and ``.. only:: latex``. This
 change will not affect any users. Only downstream package maintainers, who
 have used the proprietary directives in their docs, will have to switch to the
 sphinx directives.

doc/devel/MEP/MEP11.rst

@@ -32,10 +32,10 @@ alongside matplotlib.  This MEP aims to resolve some problems with
 that approach, bring some consistency, while continuing to make
 installation convenient.
 
-At the time that was initially done, `setuptools`, `easy_install` and
-`PyPI` were not mature enough to be relied on.  However, at present,
+At the time that was initially done, setuptools_, easy_install_ and
+PyPI_ were not mature enough to be relied on.  However, at present,
 we should be able to safely leverage the "modern" versions of those
-tools, `distribute` and `pip`.
+tools, distribute_ and pip_.
 
 While matplotlib has dependencies on both Python libraries and C/C++
 libraries, this MEP addresses only the Python libraries so as to not
@@ -59,38 +59,38 @@ matplotlib depends on the following third-party Python libraries:
 Current behavior
 ----------------
 
-When installing from source, a `git` checkout or `pip`:
+When installing from source, a :program:`git` checkout or pip_:
 
-  - `setup.py` attempts to `import numpy`.  If this fails, the
+  - :file:`setup.py` attempts to ``import numpy``.  If this fails, the
     installation fails.
 
-  - For each of `dateutil`, `pytz` and `six`, `setup.py` attempts to
+  - For each of dateutil_, pytz_ and six_, `setup.py` attempts to
     import them (from the top-level namespace).  If that fails,
     matplotlib installs its local copy of the library into the
     top-level namespace.
 
-  - `pyparsing` is always installed inside of the matplotlib
+  - pyparsing_ is always installed inside of the matplotlib
     namespace.
 
-This behavior is most surprising when used with `pip`, because no
-`pip` dependency resolution is performed, even though it is likely to
+This behavior is most surprising when used with pip_, because no
+pip_ dependency resolution is performed, even though it is likely to
 work for all of these packages.
 
-The fact that `pyparsing` is installed in the matplotlib namespace has
+The fact that pyparsing_ is installed in the matplotlib namespace has
 reportedly (#1290) confused some users into thinking it is a
 matplotlib-related module and import it from there rather than the
 top-level.
 
-When installing using the Windows installer, `dateutil`, `pytz` and
-`six` are installed at the top-level *always*, potentially overwriting
+When installing using the Windows installer, dateutil_, pytz_ and
+six_ are installed at the top-level *always*, potentially overwriting
 already installed copies of those libraries.
 
 TODO: Describe behavior with the OS-X installer.
 
 When installing using a package manager (Debian, RedHat, MacPorts
 etc.), this behavior actually does the right thing, and there are no
 special patches in the matplotlib packages to deal with the fact that
-we handle `dateutil`, `pytz` and `six` in this way.  However, care
+we handle dateutil_, pytz_ and six_ in this way.  However, care
 should be taken that whatever approach we move to continues to work in
 that context.
 
@@ -104,9 +104,9 @@ Desired behavior
 ----------------
 
 Third-party dependencies are downloaded and installed from their
-canonical locations by leveraging `pip`, `distribute` and `PyPI`.
+canonical locations by leveraging pip_, distribute_ and PyPI_.
 
-`dateutil`, `pytz`, and `pyparsing` should be made into optional
+dateutil_, pytz_, and pyparsing_ should be made into optional
 dependencies -- though obviously some features would fail if they
 aren't installed.  This will allow the user to decide whether they
 want to bother installing a particular feature.
@@ -116,31 +116,31 @@ Implementation
 
 For installing from source, and assuming the user has all of the
 C-level compilers and dependencies, this can be accomplished fairly
-easily using `distribute` and following the instructions `here
+easily using distribute_ and following the instructions `here
 <https://pypi.python.org/pypi/distribute>`_.  The only anticipated
-change to the matplotlib library code will be to import `pyparsing`
+change to the matplotlib library code will be to import pyparsing_
 from the top-level namespace rather than from within matplotlib.  Note
-that `distribute` will also allow us to remove the direct dependency
-on `six`, since it is, strictly speaking, only a direct dependency of
-`dateutil`.
+that distribute_ will also allow us to remove the direct dependency
+on six_, since it is, strictly speaking, only a direct dependency of
+dateutil_.
 
 For binary installations, there are a number of alternatives (here
 ordered from best/hardest to worst/easiest):
 
     1. The distutils wininst installer allows a post-install script to
-       run.  It might be possible to get this script to run `pip` to
+       run.  It might be possible to get this script to run pip_ to
        install the other dependencies.  (See `this thread
        <http://grokbase.com/t/python/distutils-sig/109bdnfhp4/distutils-ann-setuptools-post-install-script-for-bdist-wininst>`_
        for someone who has trod that ground before).
 
-    2. Continue to ship `dateutil`, `pytz`, `six` and `pyparsing` in
+    2. Continue to ship dateutil_, pytz_, six_ and pyparsing_ in
        our installer, but use the post-install-script to install them
        *only* if they can not already be found.
 
     3. Move all of these packages inside a (new) `matplotlib.extern`
        namespace so it is clear for outside users that these are
        external packages.  Add some conditional imports in the core
-       matplotlib codebase so `dateutil` (at the top-level) is tried
+       matplotlib codebase so dateutil_ (at the top-level) is tried
        first, and failing that `matplotlib.extern.dateutil` is used.
 
 2 and 3 are undesirable as they still require maintaining copies of
@@ -164,7 +164,17 @@ accessing the network).
 Alternatives
 ============
 
-Distributing binary `eggs` doesn't feel like a usable solution.  That
-requires getting `easy_install` installed first, and Windows users
-generally prefer the well known `.exe` or `.msi` installer that works
+Distributing binary eggs doesn't feel like a usable solution.  That
+requires getting easy_install_ installed first, and Windows users
+generally prefer the well known ``.exe`` or ``.msi`` installer that works
 out of the box.
+
+.. _PyPI: https://pypi.org
+.. _dateutil: https://pypi.org/project/python-dateutil/
+.. _distribute: https://pypi.org/project/distribute/
+.. _pip: https://pypi.org/project/pip/
+.. _pyparsing: https://pypi.org/project/pyparsing/
+.. _pytz: https://pypi.org/project/pytz/
+.. _setuptools: https://pypi.org/project/setuptools/
+.. _six: https://pypi.org/project/six/
+.. _easy_install: https://setuptools.readthedocs.io/en/latest/easy_install.html

doc/devel/MEP/MEP12.rst

@@ -18,7 +18,7 @@ Branches and Pull requests
 
 #1623, #1924, #2181
 
-PR `#2474 <https://github.com/matplotlib/matplotlib/pull/2474`>_
+PR `#2474 <https://github.com/matplotlib/matplotlib/pull/2474>`_
 demonstrates a single example being cleaned up and moved to the
 appropriate section.
 

doc/devel/MEP/MEP23.rst

@@ -51,7 +51,7 @@ the `Toolbar` makes it pretty hard to switch between canvases.
 Implementation
 ==============
 
-The first implementation will be done in `GTK3` using a Notebook as
+The first implementation will be done in GTK3 using a Notebook as
 canvas container.
 
 `FigureManagerBase`

doc/devel/MEP/MEP26.rst

@@ -34,17 +34,17 @@ Detailed description
 ====================
 
 Currently, the look and appearance of existing artist objects (figure,
-axes, Line2D etc...) can only be updated via `set_` and `get_` methods
+axes, Line2D etc...) can only be updated via ``set_`` and ``get_`` methods
 on the artist object, which is quite laborious, especially if no
 reference to the artist(s) has been stored.  The new style sheets
 introduced in 1.4 allow styling before a plot is created, but do not
 offer any means to dynamically update plots or distinguish between
-artists of the same type (i.e. to specify the `line color` and `line
-style` separately for differing `Line2D` objects).
+artists of the same type (i.e. to specify the ``line color`` and ``line
+style`` separately for differing `.Line2D` objects).
 
 The initial development should concentrate on allowing styling of
-artist primitives (those `artists` that do not contain other
-`artists`), and further development could expand the CSS syntax rules
+artist primitives (those `.Artist`\s that do not contain other
+`.Artist`\s), and further development could expand the CSS syntax rules
 and parser to allow more complex styling. See the appendix for a list
 of primitives.
 
@@ -67,10 +67,10 @@ Implementation
 
 It will be easiest to allow a '3rd party' to modify/set the style of
 an artist if the 'style' is created as a separate class and store
-against the artist as a property.  The `GraphicsContext` class already
+against the artist as a property.  The `.GraphicsContext` class already
 provides a the basis of a `Style` class and an artists `draw` method can
 be refactored to use the `Style` class rather than setting up it's own
-`GraphicsContext` and transferring it's style-related properties to
+`.GraphicsContext` and transferring it's style-related properties to
 it.  A minimal example of how this could be implemented is shown here:
 https://github.com/JamesRamm/mpl_experiment
 
@@ -103,7 +103,7 @@ the syntax is given below and then explained ::
 
     propValue ::= Ident | Number | Colour | "None"
 
-`ArtistIdent`, `Ident`, `Number` and `Colour` are tokens (the basic
+``ArtistIdent``, ``Ident``, ``Number`` and ``Colour`` are tokens (the basic
 building blocks of the expression) which are defined by regular
 expressions.
 
@@ -116,14 +116,14 @@ syntax ::
 
     selector {attribute: value;}
 
-Each rule can have any number of `attribute`: `value` pairs, and a
+Each rule can have any number of ``attribute: value`` pairs, and a
 stylesheet can have any number of rules.
 
-The initial syntax is designed only for `artist` primitives. It does
-not address the question of how to set properties on `container` types
-(whose properties may themselves be `artists` with settable
+The initial syntax is designed only for `.Artist` primitives. It does
+not address the question of how to set properties on `.Container` types
+(whose properties may themselves be `.Artist`\s with settable
 properties), however, a future solution to this could simply be nested
-`RuleSet` s
+``RuleSet``\s
 
 Selectors
 ~~~~~~~~~
@@ -138,22 +138,22 @@ initial development:
 Artist Type Selector
 
 
-Select an `artist` by it's type. E.g `Line2D` or `Text`::
+Select an `.Artist` by it's type. E.g `.Line2D` or `.Text`::
 
     Line2D {attribute: value}
 
-The regex for matching the artist type selector (`ArtistIdent` in the BNF grammar) would be::
+The regex for matching the artist type selector (``ArtistIdent`` in the BNF grammar) would be::
 
     ArtistIdent = r'(?P<ArtistIdent>\bLine2D\b|\bText\b|\bAxesImage\b|\bFigureImage\b|\bPatch\b)'
 
 GID selector
 ~~~~~~~~~~~~
 
-Select an `artist` by its `gid`::
+Select an `.Artist` by its ``gid``::
 
     Line2D#myGID {attribute: value}
 
-A `gid` can be any string, so the regex could be as follows::
+A ``gid`` can be any string, so the regex could be as follows::
 
     Ident = r'(?P<Ident>[a-zA-Z_][a-zA-Z_0-9]*)'
 
@@ -164,15 +164,15 @@ The above selectors roughly correspond to their CSS counterparts
 Attributes and values
 ~~~~~~~~~~~~~~~~~~~~~
 
-- `Attributes` are any valid (settable) property for the `artist` in question.
-- `Values` are any valid value for the property (Usually a string, or number).
+- ``Attributes`` are any valid (settable) property for the `.Artist` in question.
+- ``Values`` are any valid value for the property (Usually a string, or number).
 
 Parsing
 -------
 
 Parsing would consist of breaking the stylesheet into tokens (the
 python cookbook gives a nice tokenizing recipe on page 66), applying
-the syntax rules and constructing a `Tree`. This requires defining the
+the syntax rules and constructing a ``Tree``. This requires defining the
 grammar of the stylesheet (again, we can borrow from CSS) and writing
 a parser. Happily, there is a recipe for this in the python cookbook
 aswell.
@@ -184,7 +184,7 @@ Visitor pattern for matplotlib figure
 In order to apply the stylesheet rules to the relevant artists, we
 need to 'visit' each artist in a figure and apply the relevant rule.
 Here is a visitor class (again, thanks to python cookbook), where each
-`node` would be an artist in the figure. A `visit_` method would need
+``node`` would be an artist in the figure. A ``visit_`` method would need
 to be implemented for each mpl artist, to handle the different
 properties for each ::
 
@@ -196,18 +196,18 @@ properties for each ::
               raise NotImplementedError
            return meth(node)
 
-An `evaluator` class would then take the stylesheet rules and
+An ``evaluator`` class would then take the stylesheet rules and
 implement the visitor on each one of them.
 
 
 
 Backward compatibility
 ======================
 
-Implementing a separate `Style` class would break backward
+Implementing a separate ``Style`` class would break backward
 compatibility as many get/set methods on an artist would become
 redundant.  While it would be possible to alter these methods to hook
-into the `Style` class (stored as a property against the artist), I
+into the ``Style`` class (stored as a property against the artist), I
 would be in favor of simply removing them to both neaten/simplify the
 codebase and to provide a simple, uncluttered API...
 

doc/devel/documenting_mpl.rst

@@ -158,7 +158,7 @@ Referring to other documents and sections
 
 Sphinx_ allows internal references_ between documents.
 
-Documents can be linked with the `:doc:` directive:
+Documents can be linked with the ``:doc:`` directive:
 
 .. code-block:: rst
 
@@ -640,7 +640,7 @@ If a subclass overrides a method but does not change the semantics, we can
 reuse the parent docstring for the method of the child class. Python does this
 automatically, if the subclass method does not have a docstring.
 
-Use a plain comment `# docstring inherited` to denote the intention to reuse
+Use a plain comment ``# docstring inherited`` to denote the intention to reuse
 the parent docstring. That way we do not accidentally create a docstring in
 the future::
 
@@ -661,8 +661,8 @@ Adding figures
 --------------
 
 As above (see :ref:`rst-figures-and-includes`), figures in the examples gallery
-can be referenced with a `:plot:` directive pointing to the python script that
-created the figure.  For instance the `~.Axes.legend` docstring references
+can be referenced with a ``:plot:`` directive pointing to the python script
+that created the figure.  For instance the `~.Axes.legend` docstring references
 the file :file:`examples/text_labels_and_annotations/legend.py`:
 
 .. code-block:: python
@@ -751,7 +751,7 @@ Tutorials are made with the exact same mechanism, except they are longer, and
 typically have more than one comment block (i.e.
 :doc:`/tutorials/introductory/usage`).  The first comment block
 can be the same as the example above.  Subsequent blocks of ReST text
-are delimited by a line of `###` characters:
+are delimited by a line of ``###`` characters:
 
 .. code-block:: python