DOC: yet more re-organization / consolidation

Author: tacaswell

doc/users/annotations_guide.rst renamed to doc/users/annotations.rst

@@ -1,18 +1,108 @@
-.. _plotting-guide-annotation:
+============
+ Annotation
+============
+
+.. contents:: Table of Contents
+   :depth: 3
+
+.. _annotations-tutorial:
+
+Basic annotation
+================
+
+The uses of the basic :func:`~matplotlib.pyplot.text` command above
+place text at an arbitrary position on the Axes.  A common use case of
+text is to annotate some feature of the plot, and the
+:func:`~matplotlib.Axes.annotate` method provides helper functionality
+to make annotations easy.  In an annotation, there are two points to
+consider: the location being annotated represented by the argument
+``xy`` and the location of the text ``xytext``.  Both of these
+arguments are ``(x,y)`` tuples.
+
+.. plot:: pyplots/annotation_basic.py
+   :include-source:
+
+
+In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
+(text location) are in data coordinates.  There are a variety of other
+coordinate systems one can choose -- you can specify the coordinate
+system of ``xy`` and ``xytext`` with one of the following strings for
+``xycoords`` and ``textcoords`` (default is 'data')
+
+====================  ====================================================
+argument              coordinate system
+====================  ====================================================
+  'figure points'     points from the lower left corner of the figure
+  'figure pixels'     pixels from the lower left corner of the figure
+  'figure fraction'   0,0 is lower left of figure and 1,1 is upper right
+  'axes points'       points from lower left corner of axes
+  'axes pixels'       pixels from lower left corner of axes
+  'axes fraction'     0,0 is lower left of axes and 1,1 is upper right
+  'data'              use the axes data coordinate system
+====================  ====================================================
+
+For example to place the text coordinates in fractional axes
+coordinates, one could do::
+
+    ax.annotate('local max', xy=(3, 1),  xycoords='data',
+                xytext=(0.8, 0.95), textcoords='axes fraction',
+                arrowprops=dict(facecolor='black', shrink=0.05),
+                horizontalalignment='right', verticalalignment='top',
+                )
+
+For physical coordinate systems (points or pixels) the origin is the
+(bottom, left) of the figure or axes.  If the value is negative,
+however, the origin is from the (right, top) of the figure or axes,
+analogous to negative indexing of sequences.
+
+Optionally, you can specify arrow properties which draws an arrow
+from the text to the annotated point by giving a dictionary of arrow
+properties in the optional keyword argument ``arrowprops``.
+
+
+==================== =====================================================
+``arrowprops`` key   description
+==================== =====================================================
+width                the width of the arrow in points
+frac                 the fraction of the arrow length occupied by the head
+headwidth            the width of the base of the arrow head in points
+shrink               move the tip and base some percent away from
+                     the annotated point and text
+
+\*\*kwargs           any key for :class:`matplotlib.patches.Polygon`,
+                     e.g., ``facecolor``
+==================== =====================================================
+
+
+In the example below, the ``xy`` point is in native coordinates
+(``xycoords`` defaults to 'data').  For a polar axes, this is in
+(theta, radius) space.  The text in this example is placed in the
+fractional figure coordinate system. :class:`matplotlib.text.Text`
+keyword args like ``horizontalalignment``, ``verticalalignment`` and
+``fontsize are passed from the `~matplotlib.Axes.annotate` to the
+``Text`` instance
+
+.. plot:: pyplots/annotation_polar.py
+   :include-source:
+
+For more on all the wild and wonderful things you can do with
+annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
+and :ref:`pylab_examples-annotation_demo`.
 
-****************
-Annotating Axes
-****************
 
 Do not proceed unless you already have read :ref:`annotations-tutorial`,
 :func:`~matplotlib.pyplot.text` and
 :func:`~matplotlib.pyplot.annotate`!
 
 
+.. _plotting-guide-annotation:
+
+Advanced Annotation
+===================
 
 
 Annotating with Text with Box
-=============================
+-----------------------------
 
 Let's start with a simple example.
 
@@ -70,7 +160,7 @@ of bbox argument when initializing the text instance) ::
 
 
 Annotating with Arrow
-=====================
+---------------------
 
 The :func:`~matplotlib.pyplot.annotate` function in the pyplot module
 (or annotate method of the Axes class) is used to draw an arrow
@@ -189,7 +279,7 @@ lower-left corner and (1,1) means top-right.
 
 
 Placing Artist at the anchored location of the Axes
-===================================================
+---------------------------------------------------
 
 There are class of artist that can be placed at the anchored location
 of the Axes. A common example is the legend.  This type of artists can
@@ -264,7 +354,7 @@ Note that unlike the legend, the ``bbox_transform`` is set
 to IdentityTransform by default.
 
 Using Complex Coordinate with Annotation
-========================================
+----------------------------------------
 
 The Annotation in matplotlib support several types of coordinate as
 described in :ref:`annotations-tutorial`. For an advanced user who wants
@@ -343,7 +433,7 @@ more control, it supports a few other options.
     You may take a look at this example :ref:`pylab_examples-annotation_demo3`.
 
 Using ConnectorPatch
-====================
+--------------------
 
 The ConnectorPatch is like an annotation without a text.  While the
 annotate function is recommended in most of situation, the
@@ -370,10 +460,10 @@ drawing order to prevent overlap (?) by other axes.
 
 
 Advanced Topics
-***************
+~~~~~~~~~~~~~~~
 
 Zoom effect between Axes
-========================
+------------------------
 
 mpl_toolkits.axes_grid.inset_locator defines some patch classes useful
 for interconnect two axes. Understanding the code requires some
@@ -385,7 +475,7 @@ straight forward.
 
 
 Define Custom BoxStyle
-======================
+----------------------
 
 You can use a custom box style. The value for the ``boxstyle`` can be a
 callable object in following forms.::

doc/users/annotations_intro.rst

@@ -0,0 +1,16 @@
+.. _color-index:
+
+========
+ Colors
+========
+
+.. htmlonly::
+
+    :Release: |version|
+    :Date: |today|
+
+.. toctree::
+
+   colors.rst
+   colormaps.rst
+   colormapnorms.rst