SF.net SVN: matplotlib: [5366] trunk/matplotlib/doc

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Revision: 5366
          http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5366&view=rev
Author:   jdh2358
Date:     2008-06-02 11:52:09 -0700 (Mon, 02 Jun 2008)

Log Message:
-----------
a couple of FAQs

Modified Paths:
--------------
    trunk/matplotlib/doc/devel/documenting_mpl.rst
    trunk/matplotlib/doc/devel/index.rst
    trunk/matplotlib/doc/faq/howto_faq.rst
    trunk/matplotlib/doc/faq/installing_faq.rst
    trunk/matplotlib/doc/faq/troubleshooting_faq.rst
    trunk/matplotlib/doc/users/artists.rst
    trunk/matplotlib/doc/users/index.rst

Modified: trunk/matplotlib/doc/devel/documenting_mpl.rst
===================================================================

--- trunk/matplotlib/doc/devel/documenting_mpl.rst	2008-06-02 18:26:43 UTC (rev 5365)
+++ trunk/matplotlib/doc/devel/documenting_mpl.rst	2008-06-02 18:52:09 UTC (rev 5366)
@@ -77,3 +77,30 @@
 
    .. literalinclude:: ../mpl_data/matplotlibrc
 
+
+Internal section references
+===========================
+
+To maximize internal consistency in section labeling and references,
+use hypen separated, descriptive labels for section references, eg::
+
+    .. _howto-webapp:
+
+and refer to it using  the standard reference syntax::
+
+    See :ref:`howto-webapp`
+
+Keep in mind that we may want to reorganize the contents later, so
+let's avoid top level names in references like ``user`` or ``devel``
+or ``faq`` unless necesssary, because for example the FAQ "what is a
+backend?" could later become part of the users guide, so the label::
+
+    .. _what-is-a-backend
+
+is better than::
+
+    .. _faq-backend
+
+In addition, since underscores are widely used by Sphinx itself, let's prefer hyphens to separate words.
+
+

Modified: trunk/matplotlib/doc/devel/index.rst
===================================================================
--- trunk/matplotlib/doc/devel/index.rst	2008-06-02 18:26:43 UTC (rev 5365)
+++ trunk/matplotlib/doc/devel/index.rst	2008-06-02 18:52:09 UTC (rev 5366)
@@ -1,4 +1,4 @@
-.. _developers_guide-index:
+.. _developers-guide-index:
 
 ###################################
   The Matplotlib Developers's Guide

Modified: trunk/matplotlib/doc/faq/howto_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/howto_faq.rst	2008-06-02 18:26:43 UTC (rev 5365)
+++ trunk/matplotlib/doc/faq/howto_faq.rst	2008-06-02 18:52:09 UTC (rev 5366)
@@ -2,6 +2,33 @@
 HOWTO
 *****
 
+.. _howto-ticks:
+
+How do I configure the tick linewidths?
+=======================================
+
+In matplotlib, the ticks are *markers*.  All
+:class:`~matplotlib.lines.Line2D` objects support a line (solid,
+dashed, etc) and a marker (circle, square, tick).  The tick linewidth
+is controlled by the "markeredgewidth" property::
+
+    import matplotlib.pyplot as plt
+    fig = plt.figure()
+    ax = fig.add_subplot(111)
+    ax.plot(range(10))
+
+    for line in ax.get_xticklines() + ax.get_yticklines():
+        line.set_markersize(10)
+
+    plt.show()
+
+The other properties that control the tick marker, and all markers,
+are ``markerfacecolor``, ``markeredgecolor``, ``markeredgewidth``,
+``markersize``.  For more information on configuring ticks, see
+:ref:`artist-tut-axis` and :ref:`artist-tut-tick`.
+
+.. _howto-webapp:
+
 How do I use matplotlib in a web application server?
 ====================================================
 
@@ -24,6 +51,9 @@
     matplotlib.use('Agg')
     import matplotlib.pyplot as plt
 
+For more on configuring your backend, see
+:ref:`what-is-a-backend`.
+
 Alternatively, you can avoid pylab/pyplot altogeher, which will give
 you a little more control, by calling the API directly as shown in
 `agg_oo.py <http://matplotlib.sf.net/examples/api/agg_oo.py>`_ .
@@ -50,7 +80,7 @@
 
 TODO
 
-How do I use matplotlib with dhango?
+How do I use matplotlib with django?
 ------------------------------------
 
 TODO

Modified: trunk/matplotlib/doc/faq/installing_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/installing_faq.rst	2008-06-02 18:26:43 UTC (rev 5365)
+++ trunk/matplotlib/doc/faq/installing_faq.rst	2008-06-02 18:52:09 UTC (rev 5366)
@@ -2,10 +2,12 @@
  Installation FAQ
 ==================
 
+
+
 How do I report a compilation problem?
 ======================================
 
-See :ref:`reporting_problems`.
+See :ref:`reporting-problems`.
 
 How do I cleanly rebuild and reinstall everything?
 ==================================================
@@ -26,4 +28,98 @@
       find the location of this directory by doing::
 
           import matplotlib
-          print matplotlib.get_configdir()
\ No newline at end of file
+          print matplotlib.get_configdir()
+
+.. _what-is-a-backend:
+
+What is a backend?
+==================
+
+A lot of documentation on the website and in the mailing lists refers
+to the "backend" and many new users are confused by this term.
+matplotlib targets many different use cases and output formats.  Some
+people use matplotlib interactively from the python shell and have
+plotting windows pop up when they type commands.  Some people embed
+matplotlib into graphical user interfaces like wxpython or pygtk to
+build rich applications.  Others use matplotlib in batch scripts, to
+generate postscript images from some numerical simulations, and still
+others in web application servers to dynamically serve up graphs.
+
+To support all of these use cases, matplotlib can target different
+outputs, and each of these capabililities is called a backend (the
+"frontend" is the user facing code, ie the plotting code, whereas the
+"backend" does all the dirty work behind the scenes to make the
+figure.  There are two types of backends: user interface backends (for
+use in pygtk, wxpython, tkinter, qt or fltk) and hardcopy backends to
+make image files (PNG, SVG, PDF, PS).
+
+There are a two primary ways to configure your backend.  One is to set
+the ``backend`` parameter in you ``matplotlibrc`` file (see
+link:Configuring)::
+
+    backend : WXAgg   # use wxpython with antigrain (agg) rendering  
+
+The other is to use the matplotlib :func:`~matplotlib.use` directive::
+
+    import matplotlib
+    matplotlib.use('PS')   # generate postscript output by default
+
+If you use the ``use`` directive, this must be done before importing
+:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
+
+If you are unsure what to do, and just want to get cranking, just set
+your backend to `TkAgg`.  This will do the right thing for 95% of the
+users.  It gives you the option of running your scripts in batch or
+working interactively from the python shell, with the least amount of
+hassles, and is smart enough to do the right thing when you ask for
+postscript, or pdf, or other image formats.
+
+If however, you want to write graphical user interfaces, or a web
+application server (:ref:`howto-webapp`), or need a better
+understanding of what is going on, read on. To make things a little
+more customizable for graphical user interfaces, matplotlib separates
+the concept of the renderer (the thing that actually does the drawing)
+from the canvas (the place where the drawing goes).  The canonical
+renderer for user interfaces is ``Agg`` which uses the `antigrain
+<http://antigrain.html>`_ C++ library to make a raster (pixel) image
+of the figure.  All of the user interfaces can be used with agg
+rendering, eg ``WXAgg``, ``GTKAgg``, ``QTAgg``, ``TkAgg``.  In
+addition, some of the user interfaces support other rendering engines.
+For example, with GTK, you can also select GDK rendering (backend
+``GTK``) or Cairo rendering (backend ``GTKCairo``).
+
+For the rendering engines, one can also distinguish between vector or
+raster renderers.  Vector issue drawing commands like "draw a line
+from this point to this point" and hence are scale free, and raster
+backends generate a pixel represenation of the line whose accuracy
+depends on a DPI setting.
+
+Here is a summary of the matplotlib rendering backends:
+
+===============================   =====================================================================================
+Renderer (Filetypes)              Description
+===============================   =====================================================================================
+Agg (png)                         raster - high quality images using the `antigrain <http://antigrain.html>`_  engine
+PS  (ps, eps)                     vector - postscript output
+PDF (pdf)                         vector - portable document format
+SVG (svg)                         vector - scalar vector graphics
+Cairo (png, ps, pdf, svn, ...)    vector - `cairo graphics <http://cairographics.org>`_
+GDK (png, jpg, tiff..)            raster - the GDK drawing API for GTK
+===============================   =====================================================================================
+
+And here are the user interfaces and renderer combinations supported:
+
+============   ===================================================================================================
+Backend        Description  
+============   ===================================================================================================
+GTKAgg         Agg rendering to a GTK canvas (`pygtk <http://www.pygtk.org>`_)
+GTK            GDK rendering to a GTK canvas (not recommended) (`pygtk <http://www.pygtk.org>`_)
+GTKCairo       Cairo rendering to a GTK Canvas (`pygtk <http://www.pygtk.org>`_)
+WXAgg          Agg rendering to to a WX canvas (`wxpython <http://www.wxpython.org>`_)
+WX             Native WX drawing to a WX Canvas (not recommended) (`wxpython <http://www.wxpython.org>`_)
+TkAgg          Agg rendering to a Tkinter canvas (`tkinter <http://wiki.python.org/moin/TkInter>`_)
+QtAgg          Agg rendering to a Qt canvas (`pyqt <http://www.riverbankcomputing.co.uk/software/pyqt/intro>`_)
+Qt4Agg         Agg rendering to a Qt4 canvas (`pyqt <http://www.riverbankcomputing.co.uk/software/pyqt/intro>`_)
+FLTKAgg        Agg rendering to a FLTK canvas (`pyfltk <http://pyfltk.sourceforge.net>`)_
+============   ===================================================================================================
+

Modified: trunk/matplotlib/doc/faq/troubleshooting_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/troubleshooting_faq.rst	2008-06-02 18:26:43 UTC (rev 5365)
+++ trunk/matplotlib/doc/faq/troubleshooting_faq.rst	2008-06-02 18:52:09 UTC (rev 5366)
@@ -2,7 +2,7 @@
 Troubleshooting FAQ
 ===================
 
-.. _reporting_problems:
+.. _reporting-problems:
 
 How do I report a problem?
 ==========================

Modified: trunk/matplotlib/doc/users/artists.rst
===================================================================
--- trunk/matplotlib/doc/users/artists.rst	2008-06-02 18:26:43 UTC (rev 5365)
+++ trunk/matplotlib/doc/users/artists.rst	2008-06-02 18:52:09 UTC (rev 5366)
@@ -247,6 +247,8 @@
 'linear' or 'log'.  In this section we'll review where the various
 container objects store the ``Artists`` that you want to get at.
 
+.. _figure-container:
+
 Figure container
 ----------------
 
@@ -338,6 +340,7 @@
 texts                 A list Figure Text instances
 ================      ===============================================================
 
+.. _axes-container:
 
 Axes container
 --------------
@@ -515,6 +518,8 @@
 yaxis             matplotlib.axis.YAxis instance
 ==============    ======================================
 
+.. _axis-container:
+
 Axis containers
 ---------------
 
@@ -599,6 +604,7 @@
    :scale: 75
 
 
+.. _tick-container:
 
 Tick containers
 ---------------

Modified: trunk/matplotlib/doc/users/index.rst
===================================================================
--- trunk/matplotlib/doc/users/index.rst	2008-06-02 18:26:43 UTC (rev 5365)
+++ trunk/matplotlib/doc/users/index.rst	2008-06-02 18:52:09 UTC (rev 5366)
@@ -1,4 +1,4 @@
-.. _users_guide-index:
+.. _users-guide-index:
 
 #############################
   The Matplotlib User's Guide


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.


