Merge pull request matplotlib#3133 from tacaswell/doc_cleanup

General documentation cleanup and reference to spin-off projects.

Author: pelson

doc/api/artist_api.rst

@@ -4,11 +4,11 @@
 artists
 *******
 
-.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
+.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text matplotlib.offsetbox
    :parts: 2
 
 :mod:`matplotlib.artist`
-=============================
+========================
 
 .. automodule:: matplotlib.artist
    :members:
@@ -17,25 +17,34 @@ artists
 
 
 :mod:`matplotlib.lines`
-=============================
+=======================
 
 .. automodule:: matplotlib.lines
    :members:
    :undoc-members:
    :show-inheritance:
 
 :mod:`matplotlib.patches`
-=============================
+=========================
 
 .. automodule:: matplotlib.patches
    :members:
    :undoc-members:
    :show-inheritance:
 
 :mod:`matplotlib.text`
-=============================
+======================
 
 .. automodule:: matplotlib.text
    :members:
    :undoc-members:
    :show-inheritance:
+
+
+:mod:`matplotlib.offsetbox`
+===========================
+
+.. automodule:: matplotlib.offsetbox
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/index_backend_api.rst

@@ -9,6 +9,6 @@ backends
    backend_qt4agg_api.rst
    backend_wxagg_api.rst
    backend_pdf_api.rst
-   backend_webagg.rst
+..   backend_webagg.rst
    dviread.rst
    type1font.rst

doc/api/offsetbox.rst

@@ -4,7 +4,7 @@ patheffects
 
 
 :mod:`matplotlib.patheffects`
-=======================
+=============================
 
 .. automodule:: matplotlib.patheffects
    :members:

doc/api/patheffects_api.rst

@@ -20,10 +20,10 @@ Overview
    devel/index.rst
    mpl_toolkits/index.rst
    api/index.rst
+   examples/index.rst
    glossary/index.rst
 
 .. htmlonly::
-   - `Examples <examples/index.html>`_
 
   * :ref:`genindex`
   * :ref:`modindex`

doc/contents.rst

@@ -10,7 +10,7 @@ recommended solutions.  It is not a complete guide to Python 2 and 3
 compatibility.
 
 Welcome to the ``__future__``
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The top of every `.py` file should include the following::
 
@@ -26,7 +26,7 @@ gets used *a lot*::
     import six
 
 Finding places to use six
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The only way to make sure code works on both Python 2 and 3 is to make sure it
 is covered by unit tests.
@@ -41,7 +41,7 @@ The `six <http://pythonhosted.org/six/>`_ documentation serves as a
 good reference for the sorts of things that need to be updated.
 
 The dreaded ``\u`` escapes
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When `from __future__ import unicode_literals` is used, all string
 literals (not preceded with a `b`) will become unicode literals.
@@ -86,7 +86,7 @@ of that and still support Python 2::
     '\\u'
 
 Iteration
----------
+^^^^^^^^^
 
 The behavior of the methods for iterating over the items, values and
 keys of a dictionary has changed in Python 3.  Additionally, other
@@ -111,7 +111,7 @@ Python 2                       Python 3                       six
 ============================== ============================== ==============================
 
 Numpy-specific things
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 When specifying dtypes, all strings must be byte strings on Python 2
 and unicode strings on Python 3.  The best way to handle this is to

doc/devel/portable_code.rst

@@ -22,8 +22,9 @@ Toolkits are collections of application-specific functions that extend matplotli
 
 .. _toolkit_basemap:
 
-Basemap (*Not distributed with matplotlib*)
-============================================
+Basemap
+=======
+(*Not distributed with matplotlib*)
 
 Plots data on map projections, with continental and political
 boundaries, see `basemap <http://matplotlib.org/basemap>`_
@@ -34,8 +35,10 @@ docs.
 
 
 
-Cartopy  (*Not distributed with matplotlib*)
-============================================
+Cartopy
+=======
+(*Not distributed with matplotlib*)
+
 An alternative mapping library written for matplotlib ``v1.2`` and beyond.
 `Cartopy <http://scitools.org.uk/cartopy/docs/latest>`_ builds on top of
 matplotlib to provide object oriented map projection definitions and close
@@ -69,8 +72,9 @@ Excel.  This toolkit ships with matplotlib, but requires
 
 .. _toolkit_natgrid:
 
-Natgrid (*Not distributed with matplotlib*)
-===========================================
+Natgrid
+=======
+(*Not distributed with matplotlib*)
 
 mpl_toolkits.natgrid is an interface to natgrid C library for gridding
 irregularly spaced data.  This requires a separate installation of the
@@ -82,7 +86,7 @@ page.
 .. _toolkit_mplot3d:
 
 mplot3d
-===========
+=======
 
 :ref:`mpl_toolkits.mplot3d <toolkit_mplot3d-index>` provides some basic 3D plotting (scatter, surf,
 line, mesh) tools.  Not the fastest or feature complete 3D library out
@@ -101,3 +105,49 @@ ease displaying multiple images in matplotlib. The AxesGrid toolkit is
 distributed with matplotlib source.
 
 .. image:: /_static/demo_axes_grid.png
+
+.. _toolkit_mpldatacursor:
+
+MplDataCursor
+=============
+(*Not distributed with matplotlib*)
+
+`MplDataCursor <https://github.com/joferkington/mpldatacursor>`_ is a
+toolkit written by Joe Kington to provide interactive "data cursors"
+(clickable annotation boxes) for matplotlib.
+
+.. _prettyplotlib:
+
+prettyplotlib
+=============
+`prettyplotlib <olgabot.github.io/prettyplotlib>`_ is an extension
+to matplotlib which changes many of the defaults to make plots some
+consider more attractive.
+
+.. _hl_plotting:
+###################
+High-Level Plotting
+###################
+
+Several projects have started to provide a higher-level interface to
+matplotlib.  These are independent projects.
+
+.. _seaborn:
+
+seaborn
+=======
+(*Not distributed with matplotlib*)
+
+`seaborn <www.stanford.edu/~mwaskom/software/seaborn/>`_ is a high
+level interface for drawing statistical graphics with matplotlib. It
+aims to make visualization a central part of exploring and
+understanding complex datasets.
+
+.. _ggplot:
+
+ggplot
+======
+(*Not distributed with matplotlib*)
+
+`ggplot <https://github.com/yhat/ggplot/>`_ is a port of the R ggplot2
+to python based on matplotlib.

doc/mpl_toolkits/index.rst

@@ -2622,8 +2622,8 @@ def get_xticklabels(self, minor=False, which=None):
         Get the x tick labels as a list of :class:`~matplotlib.text.Text`
         instances.
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         minor : bool
            If True return the minor ticklabels,
            else return the major ticklabels
@@ -2875,8 +2875,8 @@ def get_yticklabels(self, minor=False, which=None):
         Get the x tick labels as a list of :class:`~matplotlib.text.Text`
         instances.
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         minor : bool
            If True return the minor ticklabels,
            else return the major ticklabels

examples/misc/developer_commit_history.py

@@ -1171,8 +1171,8 @@ def get_ticklabels(self, minor=False, which=None):
         Get the x tick labels as a list of :class:`~matplotlib.text.Text`
         instances.
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         minor : bool
            If True return the minor ticklabels,
            else return the major ticklabels

lib/matplotlib/axes/_base.py

@@ -120,8 +120,8 @@ def new_function():
     obj_type : str, optional
         The object type being deprecated.
 
-    Example
-    -------
+    Examples
+    --------
     # To warn of the deprecation of "matplotlib.name_of_module"
     warn_deprecated('1.4.0', name='matplotlib.name_of_module',
                     obj_type='module')
@@ -172,8 +172,8 @@ def new_function():
         If True, uses a PendingDeprecationWarning instead of a
         DeprecationWarning.
 
-    Example
-    -------
+    Examples
+    --------
     @deprecated('1.4.0')
     def the_function_to_deprecate():
         pass